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
[email protected]. © Copyright 1991–2011 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
[email protected]. (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
[email protected]. (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 . . . . . 136 Message Information tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Searching for an entry to modify: Advanced solution . 93 Using XML result templates with outgoing email . . . . . . . . . . . . . . . . . . 96 Using HTML content templates with outgoing email . . . . 107 Sending a query instruction to the Email Engine . 99 User-defined HTML or XML text in outgoing HTML emails . . . . . . . 89 Sending reply email: Giving a professional look to outgoing email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Using “shorthand” qualification syntax . . . . . . . 137 6 BMC Remedy Email Engine Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Using HTML result templates with outgoing email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Using header templates as a banner with outgoing email. . . . . . . 119 Sending modify instructions in HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Using the Format label . . . . . . . . 102 Chapter 4 Incoming email 105 How incoming email works . . . . . . . . . . . . . . . . .Dynamically assigning templates to outgoing email . . . . . . . . . . . . . . . . . 112 Sending a submit instruction to the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Determining message content of outgoing email . . . . . . . . . . . . . . . . . . . . . . . . 75 Sending outgoing email in HTML. . . . . . . . 132 Using variables with templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Errors tab . . . . . . 88 Character sets in outgoing mail . . . . . . . . . . . . . . 106 Using incoming email . . . 66 Displaying date/time or numeric values in email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Creating a security key . . . . 129 Creating a submit email . 71 Using the Email Messages form to send outgoing email . . . . . . . . . . . . . . . . . . 117 Sending modify instructions in plain text . . . . . . 126 Creating workflow to modify requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Including attachments with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Displaying advanced options for incoming email. . . . . . . . . . . . . . . . . . . 113 Using keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Additional restrictions. . . . . . . . . . . . 128 Creating filter workflow that triggers a Notify action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Including qualifications in your email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Sending outgoing email in plain text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Replying to email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Using templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Adding extra custom headers to outgoing SMTP emails. . . . . . . . . . . . . . 115 Using the Format label . . . . . . . . . . . . . . . . . . . . . . . 125 Using workflow to modify requests . . . . . . . . . . . . . . 128 Exporting an email template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Displaying advanced options for outgoing email. . . . . 70 Deleting email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Including attachments with incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 How modify instructions work with incoming email . . . . . . . . . . . . . . . . . . . . . 127 Creating a sample form for your modify example . . . . . . . . . . . 97 Using status templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Sending a Modify instruction to the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal Email Engine errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server label . . . . . . . . Chapter 6 Troubleshooting Troubleshooting outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global and local parameter declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a previously saved attachment to your template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating templates . . . . . . . . . . Language label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storing templates in the AR System Email Templates form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action label. . . . . . RPC Number and Authentication labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form label . . . . . . . . . . . . . . . . . . . . . . . Tips for creating or modifying templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Login. . . . . AR System API errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email transmission or instruction failures. . . . . . . . . . . . . . . . . . . . Status Template label . . . . . . . . . . . . . . . . . . . . . Exporting templates with attachments to another server . . . . . . . . . . . . Results of the user instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . !Name! or !ID! labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Character sets in incoming mail. . . . Deleting an attachment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating user instructions . . . . . . . . . . . . . . . . . . . . . . Using label/value pairs in templates . . . Preparing email templates after an upgrade . . . . . . . . . . Creating and storing a template for use with user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Incoming and outgoing mail templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of templates . . . . . . . . . . . . . . Using variables with user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result Template label . . . . . . . . . . . . and TCP Port labels . . . . . . . . . . . . . . . . . . . . . . . . Adding attachments to HTML templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request ID label . . . Key label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error and system status logs . . . . . . . . . . . . User-defined instruction templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting mail templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format label . . . . . . Sending a user instruction in an incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header Template and Footer Template labels . . . . . . . . . . . . . . . . . . . . . . Label/value pair formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending incoming email with user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying an attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Qualification label . . . . . . . . . . . . . . . . . . . . . . Password. . . . . . . . . . . . . . . . . . 179 Updating the EmailDaemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Performance and configuration settings. . . . . . 182 Recommendation for using the SMTP timeout properties . . . . . . . . . . 239 AR System Email User Instruction Templates form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Fixing common problems with the email engine . . . . . . 205 Stopping and starting the AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Determining problems with the mail server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 AR System Email Mailbox Configuration form. . . . . . . . . . . . . . . . . . 241 8 BMC Remedy Email Engine Guide . . . . . . . . . . . . 225 Creating an email content template with Submit and Query actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Temporary directories and files . 222 Creating email templates to search for fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 AR System Email Templates form. . . . . . . 232 Appendix D Email Engine forms 233 Email Engine administration forms . . . . 240 AR System Email Error Logs form . . . . . . . . . . . . . . . . . . . . . . 201 Troubleshooting startup issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Creating email debug batch files . 209 Troubleshooting email request processing and notify filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Debugging options for the Email Engine . . 226 Creating an email reply using result templates in HTML format. . . . . . . . . . . . 177 Using the EmailDaemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Defining a heap size for the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . 231 Adding a header template and a footer template . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Creating email templates that include attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Debugging the Email Engine on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Sample debug log. . . . . . . . . . . . . . . . . . . 227 Sample HTML result template . . . . . . . . . . . 198 Configuring mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . 234 AR System Email Failover Mail Server Configuration form . . . . . . . 229 Email status template in HTML format . . . . 208 Verifying permissions for the Windows accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Debugging the Email Engine on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 AR System Email Security form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Logging levels. . . . . . . . . . . . . 207 Making changes to mailbox configuration. . . . . . . . . . . . . . . . . . . . 209 Fixing issues with notifications that fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Logging problems with the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Creating email templates to perform searches using qualifications . . . . . . . . . . . . . . . . .properties file . . . . . . . . . . . . . . . . . . . . 208 Submitting requests across different time zones. . . . . . . . . . . . . . . . . . . . . . . AR System Email Association form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Instruction Parameters form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Attachment Join form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Instructions form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email Engine workflow forms . . . . AR System Email Attachments form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Messages form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Email Engine user forms . . . . . . . . . . . . . . . . . . . . . . . . . . Index 242 242 245 249 250 250 250 251 251 253 Contents 9 . . AR System Email Error Messages form . . . . . . . . . . . . . . . . . . 10 BMC Remedy Email Engine Guide . bmc.” page 12. For additional information. Preface 11 . “Obtaining system requirements and software. you must know how to use the BMC Remedy Action Request System (AR System). especially the patch requirements. See the Installation Guide. AR System documents The following table lists documentation available for AR System 7.Preface NOTE The compatibility information in the product documentation is subject to change. See the compatibility matrix at http://www. most complete information about what is officially supported.com/support). Before you explore the topics in this guide. the Form and Application Objects Guide. Unless otherwise noted. and the Workflow Objects Guide. Make sure that you understand the terms and concepts discussed in the Configuration Guide.com/support for the latest. or both. which contains all the information you require to set up and administer a basic AR System environment. on the Customer Support website (http://www. online documentation in Adobe Acrobat (PDF) format is available on AR System product installation DVDs.04. see the Installation Guide.6. Audience This guide is for administrators who install and maintain the BMC Remedy Email Engine (Email Engine). BMC Remedy User. and BMC Remedy Data Import.bmc. Carefully read the system requirements for your operating system. including BMC Remedy Developer Studio. 6. including forms. localizing. Administrators Configuration Guide BMC Remedy Mid Tier Guide Information about configuring the mid tier. The help topics still apply to version 7. Developers Information about AR System data structures. 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. For the most recent content. plug-ins. 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. and images. Information about the development of AR System applications. C API function calls. NOTE The AR System product help has not been updated for version 7. and using applications in browsers.04 You can access product help through each product’s Help menu or by clicking Help links. Programmers Programmers 12 BMC Remedy Email Engine Guide . Information about configuring AR System servers and clients. Developers/ Programmers3 including LDAP. Workflow Objects Guide Developers Information about the AR System workflow objects (active Developers links. Information about implementing a distributed AR System server environment with BMC Remedy Distributed Server Option (DSO). includes Everyone information about add-on products that extend AR System functionality and a comprehensive glossary for the entire AR System documentation set. including an introduction to using BMC Remedy Developer Studio.BMC Remedy Action Request System 7.6. and ARDBC. refer to the PDF documentation. importing and exporting data. Integration Guide Administrators Instructions for integrating AR System with external Administrators/ systems by using web services. Title Concepts Guide1 Description Audience Overview of AR System architecture and features. OLE. Programmers Database administration topics and rules related to how AR System interacts with specific databases. Instructions for installing AR System. and administering Administrators/ flashboards to display and monitor AR System information.6.04. fields. Quick reference to C API function calls. and other products. Information about monitoring and maintaining AR System Administrators/ and AR System applications to optimize performance and Developers/ solve problems. and archiving data. setting up applications for the mid tier.03. and OLE support. filters. modifying. menus. views. and escalations) and how to use them to create processes that enforce business rules. includes an overview of the data dictionary tables. Preface 13 . Instructions for configuring and using BMC Remedy Email Administrators Engine. 3 C and Java programmers who write plug-ins and clients for AR System. Instructions for using BMC Remedy Developer Studio to develop AR System forms. except the BMC emedy Migrator Guide and BMC Remedy Encryption Security Guide. For the location of the JAR file containing this online documentation. and international issues. Instructions for configuring BMC Remedy Mid Tier.04 (for example. Instructions for using AR System forms in browsers.6. Information about new features.04 Outlines procedures for installing BMC Remedy Migrator. methods.6. Information about Java classes. and open issues. see the information about plug-ins in the Integration Guide. Everyone Information about new features. 2 Application developers who use BMC Remedy Developer Studio.6. installation planning.AR System documents Title Java API Description Audience Programmers Information about Oracle Java classes. Descriptions of AR System error messages. and performing migration tasks. and applications. BMC emedy Migrator Guide setting options.6. Instructions for using BMC Remedy Data Import. methods. Instructions for using BMC Remedy Alert. BMC Remedy Encryption Provides an overview of the BMC Remedy Encryption Administrators Security 7. BMC Remedy Migrator online help Procedures for setting BMC Remedy Migrator options and performing migration tasks. compatibility.04 BMC Remedy Security products and explains how to install and configure Encryption Security Guide them. and variables that integrate with AR System. Everyone Developers Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers BMC Remedy Migrator 7. For the location of the JAR file containing this online documentation. Instructions for using BMC Remedy User. BMC Remedy Action Request System 7. and variables used Programmers to write plug-ins for AR System.04 Concepts Guide). international Everyone issues. Instructions for using BMC Remedy Approval Server to automate approval and signature processes in your organization. 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. workflow objects. compatibility. see the information about the Java API in the Integration Guide. 1 The full title of each guide includes BMC Remedy Action Request System 7. BMC Remedy Action Request System 7.6.04 14 BMC Remedy Email Engine Guide . 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 Introduction to the Email Engine 15 .Chapter 1 Introduction to the Email Engine This chapter provides an overview of the BMC Remedy Email Engine (Email Engine). submissions. You can format these emails by using templates that specify the layout of a message in plain text. or XML formats. These instructions can involve modifying form entries. submissions. When mail arrives. contents of select fields. Processing notifications—If you choose email when creating a Notify filter or escalation. When mail arrives. which can include the results of queries. The Email Engine is a stand-alone client program that you can install and run on any computer system as an independent service. The Email Engine enables users to instruct the AR System server to perform queries. These email messages can include instructions that are interpreted by the Email Engine and translated into API calls to your AR System server. or attachments when workflow is triggered. It is included as part of the AR System and does not require an additional license. or retrieving multiple entries from your AR System server. 16 BMC Remedy Email Engine Guide . Simple Mail Transfer Protocol (SMTP)—Used for outgoing mail transmissions. Post Office Protocol (POP3)—Used for incoming mails. or modifications to entries contained on your AR System server. However. or XML. copies of messages are downloaded from the mail server to your local computer and the copy of each message remains on the server. This feature is particularly useful for users without direct access (a high-speed network link) to the AR System server. this copy is removed from the server. It provides the following capabilities: Receiving mail—The Email Engine receives email messages from an email account on your company mail server. when Email Engine is used.04 About the Email Engine The Email Engine is a service that transforms email into an interface that communicates with the AR System server. you can use the Email Engine to send text messages. the Email Engine can process notifications by using workflow actions such as filters or escalations. all by using email. Additionally. The Email Engine also returns the results of such requests in email messages in the plain text. The Email Engine can connect to mail servers by using the following protocols: Internet Message Access Protocol (IMAP4)—Used for incoming mails. Sending mail—You can use the Email Engine to send email messages. HTML. HTML. NOTE You must install the Email Engine to send notifications from the AR System server. or modifications to entries.BMC Remedy Action Request System 7. submitting entries. messages are downloaded to your local computer and removed from the mail server.6. assuring uninterrupted server processing of messages. It supports Multipurpose Internet Mail Exchange (MIME) types for attachments. The Email Engine only stores the location of the AR System server where the forms are stored. as an interface that enables different email applications to work together to distribute email. including the ability to create a variety of templates and to include attachments with email messages. Users must log in to the mail server by using an email account before they can send and receive email. NOTE You can configure the logs to be stored in a local text file by specifying a handler property in the logging. The Email Engine provides additional options. see “Multiple mail server support” on page 24. incoming emails. For more information. You can define this by using the AR System Email Failover Mail Server form. NOTE The MAPI protocol for incoming and outgoing mail is disabled for 64-bit Oracle Java Virtual Machine (Oracle JVM). MBOX—Used for storing mail messages on a UNIX® platform. Email account A user account on a mail server that permits a user to transmit or receive email messages. and outgoing emails) are stored in forms within the AR System server. Chapter 1 Introduction to the Email Engine 17 . Messages are stored in a file of type mbox under the user name. when the primary mail server stops working. Examples include the Microsoft Exchange server or the UNIX sendmail program. 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.Email Engine terminology Messaging Application Programming Interface (MAPI)—Used primarily with the Microsoft Exchange Server (Windows only). see “Debugging options for the Email Engine” on page 177. Email Engine terminology Throughout this guide. For more information. All the settings for the Email Engine and all logging information (including errors. Note: An email account is not the same as an email address. Failover mail A mail server that acts as a failover system. An email account consists of a user name and often includes a password.properties file. querying for all tickets assigned to a user. Outgoing mailbox A mailbox containing the information required by the Email Engine to create and send messages. and to increase speed and scalability. The term Instruction can also be used as an alias for Action in a label/value pair. An outgoing mailbox uses separate threads running for the Creator and Sender modules to format and send outgoing messages. 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. Email messages in this email account are assumed to be directed to the Email Engine. and returning the results in HTML format. 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. An incoming mailbox uses two threads to process email in the message queue—the Receiver and Execution modules.6. and email account information (if required). a mailbox can contain such information as the name of the mail server. Query.BMC Remedy Action Request System 7. You can use this mailbox to get started with the Email Engine. and so on. logging in to the server. for example. 18 BMC Remedy Email Engine Guide . you can then change these settings or configure additional mailboxes. for example. you can then change these settings or configure additional mailboxes. As such. Submit.04 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. The installation program provides an option for creating and configuring an initial incoming mailbox. Mailboxes are configured to be either Incoming mailboxes or Outgoing mailboxes. All the modules of the Email Engine are designed to be thread safe. For more information about configuring mailboxes. or Modify. send the results of queries. You can use this mailbox to get started with the Email Engine. see “Configuring Email Engine mailboxes” on page 27. the protocol used by that mail server for sending or receiving mail. In a narrower sense. which resides on your AR System server. Email Engine architecture The Email Engine consists of multiple modules that run in threads. The installation program provides an option for creating and configuring an initial outgoing mailbox. The Email Engine uses this mailbox to send notifications. All modules run as separate threads. 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. instructions see a specific set of actions used in an email message. 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. Sender Logging Configuration Runs as a separate thread. For more information.properties file.properties file” on page 179. Runs in separate threads to maximize speed and reliability. 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. Adds messages to message queue. Chapter 1 Introduction to the Email Engine 19 . Monitors the AR System Email Messages form for outgoing messages. see “Debugging options for the Email Engine” on page 177 and “Using the EmailDaemon. Logs messages. Primarily responsible for creating an email based on a template and the data it retrieves from AR System. Execution Creator Parses and executes messages in the message queue. Formats messages to be sent.Email Engine architecture Figure 1-1: Modules and threads in Email Engine You can specify various troubleshooting parameters. errors. for example. Creates entries in AR System Email Messages form. the queue size of email messages or how finely you want to log information within a module. Reads incoming mails from the mail server. and sends formatted messages to the mail server. Due to this.BMC Remedy Action Request System 7. 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. Depending upon the NumberOfSenderThreads value and the number of configured outgoing mailboxes. 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. NOTE The number of connections for each configured outgoing mailbox depends upon the number of Sender threads. 2 Sender threads and a connection pool with 6 connections (2 connections for every mailbox) is created. 20 BMC Remedy Email Engine Guide . there are 3 configured outgoing mailboxes and the value of NumberOfSenderThreads is assumed to be 2. Figure 1-2: Threading model for multiple outgoing mailboxes As per the above figure. Figure 1-2 explains this concept in detail.04 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. Figure 1-3 on page 21 presents a sample environment for an Email Engine implementation. including the flow of activity. The Sender thread uses the connections from this connection pool for sending the outgoing messages.6. a connection pool is created. Katie and Mark. Step 1 The local administrator installs the Email Engine. After the Email Engine is started. it contacts the AR System server. Also. 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. configuring Incoming and Outgoing mailboxes to work with the company mail server. All of the steps that the Email Engine and the users must take to make this happen follow. She uses specifically formatted instructions to be read and understood by the Email Engine. Shelly composes an email instructing the Email Engine to perform a query of the HD Incident form. Chapter 1 Introduction to the Email Engine 21 .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 4 5 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 6 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. She sends this message to an email account on the company mail server that the Email Engine polls for incoming. Shelly needs a list of the latest issues stored in the Help Desk (HD) Incident form. will be copied with the results of this query. Shelly wants to make sure that her coworkers. She wants the results of this query to be returned in an easyto-read email. Step 2 After the administrator notifies the user base that the Email Engine is running. MBOX. and Katie. Step 6 The Email Engine uses the formatting instructions in the Outgoing Mailbox to construct an email message to the company mail server. However. Step 7 Shelly. the Email Engine might reside on the same system as the AR System server. Step 4 The Email Engine interprets the instructions and translates them into API calls to the AR System server. Step 5 The AR System server responds to the Email Engine API calls with the appropriate query information for the HD Incident form. 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. and Katie log in to the mail server. attempting to fulfill her query request. Many of the configuration options available are explained in the upcoming chapters. The Email Engine then transmits the message with instructions to send the message to Shelly.BMC Remedy Action Request System 7. Users feel comfortable using email to query the AR System server and to submit and modify entries. Also. the Email Engine logs in to the company mail server by using the email account information gathered during step 1. and they find the email constructed by the Email Engine. showing how the Email Engine can assign HTML templates to outgoing email. For example. and so on.6. you will learn about the other Email Engine features for processing email. 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. as you proceed through this guide. the Email Engine reads the most recent emails from this account. Mark. by using the outgoing email protocol (SMTP or MAPI). Mark. you might configure the Incoming Mailbox and Outgoing Mailbox to use the same email account on your mail server. 22 BMC Remedy Email Engine Guide . or MAPI). IMAP4. This example illustrates the relationship between the Email Engine and other systems in a simplified environment. by using one of several email protocols (POP3. Alternatively. he hears occasional grumbling in the hallway. Your environment might differ from the one presented here.04 Step 3 After waiting for a prescribed polling period. including the email that Shelly sent. which contains a neatly formatted list of the most recent requests. Because the mailbox information tells the Email Engine that this email account is to be treated as an Incoming Mailbox. Most important. Chapter 1 Introduction to the Email Engine 23 . he designs attractive HTML pages to use as header. 5 Urgent email sent to Francie Frontline Shelly Francie Frontline Realizing the importance of AR System notifications. The templates are designed so that users can quickly tell whether a ticket’s impact is urgent. He works with a graphic artist to create interesting bitmaps.Improving the appearance of your email Figure 1-4: Templates dynamically assigned through workflow Underlying Database AR System Server 3 Server executes filter workflow that triggers Notify action. or low. result. and content templates. footer. Urgent header template is dynamically assigned. Email Templates Field 1 Field 2 Field 3 Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst Template Components Email Engine 2 Email engine parses instructions. high. Instructions then translated into API calls to server. he designs a data-driven workflow that dynamically assigns the correct templates based on the ticket’s impact. Incoming Mailbox Outgoing Mailbox Email Engine Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst 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 1 Urgent email sent to incoming mailbox. the administrator takes steps to replace the plain text email generated by the Email Engine. To improve its look and feel. medium. It parses the instructions in her email. When Francie marks the ticket as Fixed. and makes the appropriate API calls to the AR System server. its importance jumps to the top of her To Do list. email notifications are formatted with a standard HTML header and result template. and the ticket opens in her browser. Figure 1-5 on page 25 depicts this functionality. She sees the Urgent email constructed by the Email Engine.BMC Remedy Action Request System 7. Step 2 The Email Engine receives the email from the mail server. Step 3 The server fires a filter that triggers a Notify action. the first-line Customer Support engineer.6. the server fires a filter Notify action. The Email Engine then transmits the message to the mail server with instructions to send the message to Francie Frontline. If the mail server being used stops working. you can specify a failover mail server. She troubleshoots and quickly resolves the problem. Multiple mail server support You can configure multiple mail servers for an Email Engine installation. Step 4 The Email Engine constructs the message according to formatting instructions contained in the Outgoing Mailbox it is using. She composes an email with status marked Urgent and sends it to the Incoming mailbox. the filter workflow creates an email notification with the Urgent header template. 24 BMC Remedy Email Engine Guide . Because the email is marked Urgent. She can now access the information she needs to close her sale. assignee. She needs information from the corporate website within the hour to close an important deal. She clicks the URL in her email. see “Dynamically assigning templates to outgoing email” on page 66. short description. But if a submission is marked Urgent. the Email Engine switches to the available failover mail server and continues processing mails. but the web server is down and her web client keeps returning errors. 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. This message consists of the field values from the HD Incident form (submitter. For each configured mail server.04 The following steps illustrate the scenario: Step 1 Shelly is visiting an important client in Chicago. status. For more information. Step 5 Francie Frontline logs in to the mail server to see if she has new mail. Shelly then receives an email notification from the system that her web access problems have been solved. Under normal circumstances. the Email Engine produces an error and stops processing. If none of the configured mail servers is working. it switches to M3 and continues processing messages as described in the preceding note. If the Email Engine detects that M1 is not working. which is M3. and if that is not yet working. it checks whether M2 is available. If M1 is still not working. and if so. and M2 and M3 are specified as failover servers. it connects to M2.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. Then. it switches to M2. If M3 is available. Yes Yes Mail Server 3: M3 In the illustration. Chapter 1 Introduction to the Email Engine 25 . if the Email Engine detects that M2 is not working. it checks for the availability of M1. it looks for the failover server for M2. The Email Engine then tries to connect to M1. Processing stops. M1 is specified as the primary mail server. However. when switching back from the failover server to the primary server.6. 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. Unicode settings are applicable to both the incoming and outgoing messages. otherwise it uses UTF-8. no change is made to stderr. NOTE You cannot change the default UTF-8 settings of the Email Engine.sh_log.sh_log (UNIX) file. an entry is added to the stderr. The email engine always sends outgoing messages in the UTF-8 format. the email engine attempts to retrieve the CHARSET of the MIME messages that were received. To accommodate multi-byte languages.BMC Remedy Action Request System 7.log or emaild. the Email Engine supports internationalization in all the entities and attributes.04 When switching from a server being currently used to its failover server. If the email engine receives the CHARSET form. it uses the same CHARSET to display email messages. For incoming messages.log (Windows) or emaild. 26 BMC Remedy Email Engine Guide . NOTE The Email Engine does not provide UTF-8 support for the MAPI protocol. ” 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 .Chapter 2 Configuring Email Engine mailboxes This chapter explains how to create and configure Email Engine mailboxes and how to set security options. parsing. Configuration information is stored in forms on the AR System database. you must create and configure outgoing and incoming mailboxes. “Email Engine forms. 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 can configure them during or after the product installation. For more information about Email Engine forms. You must configure at least one mailbox to communicate with your mail server to send or receive email. and mailbox security). you can update the configuration as discussed in this chapter. To send and receive email. To set up advanced mailbox options (such as default values. see Appendix D. to send the results of any actions from a specific incoming mailbox to a specific outgoing mailbox. NOTE To use notifications with email. You can also link outgoing mailboxes to incoming mailboxes. see “Using notifications” on page 54. 28 BMC Remedy Email Engine Guide .6.04 Configuring outgoing mailboxes You must create at least one outgoing mailbox to process outgoing mail. such as query or workflow results. 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. For more information.BMC Remedy Action Request System 7. Outgoing messages can include results from actions specified in incoming messages. as described in this section. you must designate one mailbox as your default notification mailbox. Email Server Requires SSL—Select Yes to enable Secure Sockets Layer (SSL). Email Server Name/IP—Enter the name or IP address of your company’s mail server. select either SMTP or MAPI as the Email Server Type. For more information. This field is required because a profile is used to see the MAPI email account configuration information. and set the following values in the remaining fields: MAPI (for 32-bit JVM only): Server Type—Select MAPI. 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 Name—Enter a name that describes the function of the mailbox. Email Server Password—Enter the password corresponding to the server user. or click Set Default Email Server Port to accept the default port. Email Server Port—Enter the mail server port number. Profile Name—Enter the name of the Microsoft Exchange profile that you created during the product installation. enter ARSystemEmail . 3 In the Basic Configuration tab. Email Server User—If your mail server requires authentication information before sending email. see “Configuring SSL for the Email Engine” on page 45. Polling Interval—Select a polling interval for the Email Engine to check for new outgoing email from the BMC Remedy AR System server.Configuring outgoing mailboxes Basic outgoing mailbox configuration Outgoing mailboxes support the MAPI and SMTP mail protocols. enter the email account user name. see your Microsoft Exchange documentation. 4 Click Save. Polling Interval—Select a polling interval for the Email Engine to check for new outgoing email from the BMC Remedy AR System server. SMTP only: Server Type—Select SMTP. Status—Select Enabled. Mailbox Function—Select Outgoing. For more information about Microsoft Exchange profiles. Chapter 2 Configuring Email Engine mailboxes 29 . For example.Outgoing. NOTE Review the information about advanced configuration settings in Chapter 5. 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.” on page 139.6. enter the following information in the fields above the tabs: Associated Mailbox Name—Enter the name the existing mailbox that will receive instructions from this outgoing mailbox. Default Outgoing Mailbox—Select Yes to make this outgoing mailbox route all emails that do not have a specified outgoing mailbox associated with them. including default addressing and templates.04 Advanced outgoing mailbox configuration This section describes how to specify default settings for an outgoing mailbox. “Using email templates. 30 BMC Remedy Email Engine Guide . To create an advanced configuration for your outgoing mailbox 1 In the Advanced Configuration tab of the AR System Email Mailbox Configuration form. This option is not used with MAPI.BMC Remedy Action Request System 7. Display Name—Enter a descriptive name that appears in the From: line of outgoing emails. The AR System Email Templates form must already contain the templates. see “Defining workflow to send email notifications” on page 55.Configuring outgoing mailboxes Email Address—Enter the email address of the server user that you created during the product installation. Chapter 2 Configuring Email Engine mailboxes 31 . To save workflow-generated messages in the AR System Email Messages form. Organization—If your email client displays your organization’s name. Default BCC—Enter all email addresses that should receive blind copies of outgoing messages from this mailbox if no other email address is specified in the message. 2 Specify Default Addressing for notifications and escalations: Default To—Enter all email addresses that should receive outgoing messages from this mailbox if no other email address is specified in the message. Default CC—Enter all email addresses that should receive copies of outgoing messages from this mailbox if no other email address is specified in the message. This option is not used with MAPI. Delete Outgoing Notification Messages—To have workflow-generated notification messages deleted from the AR System Email Messages form after they have been sent from this mailbox. System administrators or other users with the appropriate permissions must delete manual messages. select No. if you entered a display name of ARSystem and an email address of arsystem@bmc. the From: line would be: From: ARSystem [arsystem@bmc. Reply To Address—Specify an email address where replies to your outgoing emails will be sent.com] This option is not used with MAPI. or accept the default server user email address already in this field. For example. Footer Template—Enter name of the template to use for the message footer if no other footer template is specified. enter the name of the organization or company. 3 Specify Default Templates for notifications and escalations: Header Template—Enter the name of the template to use for the message header if no other header template is specified. Status Template—Enter name of the template to use for the status if no other status template is specified. 4 Click Save. For more information about notifications and escalations. Result Template—Enter the name of the template to use for the result if no other result template is specified. select Yes. or if you are going to use email templates to modify records.com. Incoming. the Email Engine polls incoming mailboxes for new messages. 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. Status—Select Enabled.6. or MBOX as the Email Server Type. POP3. and performs the actions specified in the messages. Polling Interval—Select a polling interval for the Email Engine to check for new incoming email from the mail server. 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. This field is required because a profile is used to see the MAPI email account configuration information. 2 Enter the following information in the fields above the tabs: Mailbox Name—Enter a name that describes the function of the mailbox. IMAP4. Profile Name—Enter the name of the Microsoft Exchange profile that you created during the product installation. For more information about Microsoft Exchange profiles. enter ARSystemEmail . select MAPI. For example. and MBOX mail protocols. parses the contents if necessary. such as the mailbox name Server information.BMC Remedy Action Request System 7. Mailbox Function—Select Incoming. processes the messages.04 Configuring incoming mailboxes Based on the information that you enter in the AR System Email Mailbox Configuration form. 32 BMC Remedy Email Engine Guide . Incoming mailboxes support the MAPI. see your Microsoft Exchange documentation. POP3. and set the following values in the remaining fields: MAPI (for 32-bit JVM only): Server Type—Select MAPI. IMAP4. 3 In the Basic Configuration tab. such as modifying requests or executing queries. Email Server Password—Enter the password corresponding to the server user. Advanced incoming mailbox configuration During advanced configuration. For example. Polling Interval—Select a polling interval for the Email Engine to check for new incoming email from the mail server. MBOX only: Server Type—Select MBOX. and information related to mailbox security. Email Server Requires SSL—Select Yes to enable Secure Sockets Layer (SSL). or click Set Default Email Server Port to accept the default port.Configuring incoming mailboxes POP3 or IMAP4 only: Server Type—Select either POP3 or IMAP4. Email Server Port—Enter the mail server port number. you enter information about associated mailboxes. see “Configuring SSL for the Email Engine” on page 45. templates. and forms. Chapter 2 Configuring Email Engine mailboxes 33 . Polling Interval—Select a polling interval for the Email Engine to check for new incoming email from the mail server. Inbox Path—Enter the complete path to the MBOX file that corresponds to the user email account. enter /usr/spool/mail/ARSystem. 4 Click Save. where ARSystem is the file name. For more information. You can do this by using the Advanced Configuration tab of the AR System Email Mailbox Configuration form as shown in Figure 2-3. Email Server Name/IP—Enter the name or IP address of your company’s mail server. Email Server User—If your mail server requires authentication information before sending email. enter the email account user name. such as queries. select Yes. 34 BMC Remedy Email Engine Guide . To use normal parsing. For more information about templates and parsing. such as a character string in a number field. you must select Parse. NOTE If you select No. If you use templates to perform Submit.6. and data entered in an invalid format. Use Original Template Format (enabled for upgrades from BMC Remedy Mail Server)—To enable original parsing system processing.BMC Remedy Action Request System 7. select an outgoing mailbox from the Associated Mailbox Name list to reply to incoming emails that require responses.” on page 139. or Query actions. Original parsing ignores special HTML fields. 2 In the Action Configuration section. XML formats. specify: Email Action—To enable the Email Engine to detect and process instructions included in an incoming email message. Modify. select Parse. “Using email templates. make sure that multiple lines in emails are encapsulated with the [$$ and $$] multiple-line delimiters. see “Using label/value pairs in templates” on page 146 and “Incoming and outgoing mail templates” on page 141. If you use this option.04 Figure 2-3: Advanced configuration for incoming mailboxes NOTE Review the information about advanced configuration settings in Chapter 5. To create an advanced configuration for your incoming mailbox 1 In the Advanced Configuration tab of the AR System Email Mailbox Configuration form. the Email Engine returns an error when it encounters these types of fields or formats. select No. select Yes. For more information. form-entry modifications. select Yes. and form submittals. see “Form label” on page 147. see “Login. For more information. Enable Modify Actions—To enable the Email Engine to modify existing entries. For more information about login syntax. Use Security Key—Select Yes to enable a security key for incoming email. select Yes. you must create and configure the security key. specify the level of security to be applied to email messages to this mailbox. from the incoming email message. NOTE If you define a default workflow form. If you use this option. select Yes. You can apply any or all of these security options. Password. select Yes. 4 Click Save. Chapter 2 Configuring Email Engine mailboxes 35 .Configuring incoming mailboxes Reply with Result—To enable the Email Engine to return the results of an action in an email. Use Supplied User Information—To use AR System server login information from the incoming email message to execute instructions in the incoming message. the schema will not be processed and the default workflow form will be used instead. Default Workflow Form—Enter the name of the default form on which the Email Engine executes instructions such as queries. Force Default Workflow Form—To confine all instructions from the incoming email message to the form that you specified in the Default Workflow Form field. depending on the level of security that you want. and TCP Port labels” on page 147. This option allows the email sender to know if the incoming email succeeded or failed. See “Configuring incoming mailbox security” on page 39. Use Email From Address—To use the sender’s email address as a form of authentication. 3 In the Incoming Security Configuration section. so you do not have to supply the user name and password in the incoming email. select Yes. This information is used to determine which AR System user information to apply when executing instructions parsed from an incoming email. see “Action label” on page 149. such as instructions to modify requests or submit queries. NOTE If an incoming template specifies a schema. Reply with Entry—To return the complete entry of a submit or modify action. The Email Engine returns an error if the sender’s email address is different from the email address stored in the AR System User form. incoming templates do not require the Form (or Schema) label. The information is added to the Email Security form. 6 Perform a query for the email message that you sent. as shown in Figure 2-4. Use the following procedures to verify that you can send email from your outgoing mailbox and receive email in your incoming mailbox. and the body content. 2 In BMC Remedy User. If you complete the steps successfully.04 Testing your mailbox configuration You must test your mailbox configurations to make sure that your mailbox communicates with your mail server correctly. 36 BMC Remedy Email Engine Guide . To test your outgoing mailbox 1 In the Basic Configuration tab of the outgoing mailbox you are testing. Before you perform the test. open the AR System Email Messages form in New mode. 3 Create a message as follows: a Mailbox Name—Select the name of the outgoing mailbox to test. c Message Tab—Enter email addresses for the From: and Reply To: fields.BMC Remedy Action Request System 7. 7 In the results table. b Message Type—Select Outgoing. 5 Open the AR System Email Messages form in Search mode. If you are unable to complete the steps.” for more information. such as Microsoft Outlook. obtain the correct email address for your email account or profile from your email server administrator. your outgoing and incoming mailboxes are configured correctly. NOTE Choose an email address that you can access with a third-party utility. to view the test results promptly. a subject line. “Troubleshooting. skip this section and see “About email security” on page 38. set the Polling Interval to one minute. NOTE If your Email Engine requires a security key to authenticate incoming email. see Chapter 6.6. The value in the Send Message column is Yes. A Yes value indicates that the outgoing mailbox has queued your email to be sent. check for the following information: An entry corresponding to the email message. 4 Click Send. open the AR System Email Messages form in Search mode. as shown in Figure 2-5 on page 38. and change the form entry if necessary. verify that the message was sent to the To address that you specified in step 3c on page 36. create an email containing a subject line and body content. 5 In a third-party email client. 7 After the time specified for the incoming mailbox’s polling interval. 2 In BMC Remedy User. 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. To test your incoming mailbox 1 In the Basic Configuration tab of the incoming mailbox you are testing. and click Search. The results table displays the entry corresponding to the message you sent. 11 In the results table. to view the test results promptly. open the AR System Email Messages form in Search mode. check for the following information: An entry corresponding to the email message. 8 Select a mailbox name and perform a search. 9 After the time specified for the outgoing mailbox’s polling interval. 12 Using a third-party email client. set the Polling Interval to one minute. 6 Send the email to the email address that you verified in step 4. Chapter 2 Configuring Email Engine mailboxes 37 . open the AR System Email Mailbox Configuration form. 10 Enter the name of the outgoing mailbox. 3 Search for the name of the incoming mailbox to test. 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.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. 6. The following sections provide instructions for creating security keys for incoming email. which can include the results of query actions. If a user does not have access to the field or form being queried. As long as the email has one of these security mechanisms. the Email Engine executes the appropriate action. About email security Incoming and outgoing emails use different security mechanisms: For validation. and provide instructions for configuring the Email Engine to allow modify actions. use AR System access control for forms and fields. describe how security is handled for outgoing email. the field and its contents are not included in the outgoing email message. 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. or the user’s email address.BMC Remedy Action Request System 7.04 Figure 2-5: Test entry example 9 Double-click the entry to open the form containing the information for that entry. incoming email messages use security keys. which indicates a successful test. You can configure the Email Engine to use all three methods. Outgoing email messages. the user’s login and password. if the email message requests a modify action. only a security key can validate the user’s request. 38 BMC Remedy Email Engine Guide . however. For example. If the key is valid. do not use a favorite product nickname. To create email security keys 1 In BMC Remedy User.About email security 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. the Email Engine validates the mailbox owner name in the form. Figure 2-6: The AR System Email Security form 2 Enter the following information in the fields. Cityscape. Do not use names that are common to your working environment or that could be easy to guess. In the AR System Email Mailbox Configuration form. If you use a security key. For example. or a campus building name. you must create the key and associate it with a mailbox. When mail arrives. open the AR System Email Security form in New mode. the Email Engine validates the security key included in the incoming email message against the stored information. CITYSCAPE. such as modifying entries. Chapter 2 Configuring Email Engine mailboxes 39 . Consider the following issues before you enter the characters: Security keys are case-sensitive. and cityscape are all different. your name. as shown in Figure 2-7: Status—Select Enabled to activate the key. you specify whether a security key is required for email sent to a mailbox (see “Advanced incoming mailbox configuration” on page 33). Key—Enter a set of alphanumeric characters. City2Scape or City!Scape). forward slashes. Force from Email Addresses—To require this key for emails received from specific email addresses.04 Mix numbers. Expires—To specify an expiration date for the key. To enable the key for all mailboxes in your email environment. User Name—Enter the name of a valid AR System user to which the security key applies. select No. and special characters to make the key more difficult to guess (for example. Allows the key to work only if it comes from the mailbox contained in the email addresses field. Mailbox Name—Enter the name of the incoming mailbox to which the security key applies. explain why the key was created or include instructions to modify or delete it. or backslashes. For example. Figure 2-7: The AR System Email Security form 40 BMC Remedy Email Engine Guide . select Yes. if you enabled the Force from Email Addresses key. Do not use spaces. Expiration Date—Enter an expiration date for this security key. Description—Enter a description of the key. letters. After the key expires. The Expiration Date field is enabled.6. Force for Mailbox—To enable the security key for this mailbox only. you can either modify the expiration date in this form or select No for the Expires field.BMC Remedy Action Request System 7. Email Addresses—Enter the email addresses to which the security key applies. select Yes. select Yes. 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. To configure the Email Engine for replying with results 1 In BMC Remedy User. For example. 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. 5 (Recommended for testing purposes) Set the Delete Outgoing Notification Messages field to No. which can include the results of query actions. If a user does not have access to the field or form being queried. or modified on the form. only data allowed by Public access are included in the email. 7 Click the Advanced Configuration tab of the incoming mailbox from which you want the modify instruction sent. the form and fields queried must have Public access. If the system locks a record by using the row-level access feature.About email security Configuring outgoing mailbox security Outgoing email messages. The email contains the information that was submitted. and the AR System server must be configured to allow guest users. 2 Search for and open the records for your incoming and outgoing mailboxes. If an email that includes query results is sent to a nonregistered AR System user. 6 Save your changes. Chapter 2 Configuring Email Engine mailboxes 41 . queried. use AR System access control for forms and fields. the Email Engine sends reply email back to the sender. if an email is sent to both an administrator with full access permissions and to a user with only Public access. open the AR System Email Mailbox Configuration form in Search mode. 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. the field and its contents are not included in the outgoing email message. the record are included only if all email recipients have access to it. 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. To configure the Email Engine for modify actions 1 In BMC Remedy User. incoming email with modify instructions do not work by default. 7 Set the Use Security Key field to Yes.04 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. 8 Save your changes. 2 Search for and open the records for your incoming and outgoing mailboxes. especially if they are using email as a client to the AR System server. open the AR System Email Mailbox Configuration form in Search mode.6. Configuring the Email Engine for modify actions Modifications are executed by sending a modify instruction or modify action to the Email Engine. 5 Set the Email Action field to Parse. NOTE You must provide a security key for every user who sends modify instructions to the Email Engine. 42 BMC Remedy Email Engine Guide . 3 Make sure that you have an incoming mailbox and an outgoing mailbox associated with each other.BMC Remedy Action Request System 7. Typically. you want only trusted users making changes to records. you must configure the incoming mailbox to accept modify actions. 9 Click the Advanced Configuration tab of the outgoing mailbox from which you want the modify instruction sent. 6 Set the Enable Modify Actions field to Yes. 4 Click the Advanced Configuration tab of the incoming mailbox to which you want the modify instruction sent. For security reasons. 11 Open the AR System Email Security form in New mode. d Select either Yes or No for the Force From Email Address.About email security 10 Set the Delete Outgoing Notification Messages field to No. c Make sure that the Force For Mailbox field is set to No (default). the From Address of the reply sent by the user is checked against the security key entry’s From Address. NOTE A user making modifications must have a write license unless that user is the submitter or the Submitter Mode is set to Locked. b Create a security key. for example. This field enforces the email address that is associated with the key to be used. 12 Create a user record as follows: a Set Status to Enabled. 13 Save your changes. e Enter other information as needed. If set to Yes. an expiration date. Figure 2-8: A user entry in AR System Email Security form Set security key Chapter 2 Configuring Email Engine mailboxes 43 . Figure 2-8 shows Francie Frontline’s security key in the AR System Email Security form. For example.properties file. it retrieves all the entries in the AR System Email Mailbox Configuration form and creates incoming and outgoing mailboxes. NOTE Changes to the Status field are not reflected automatically. To enable changes to form entries before the next default query time.BMC Remedy Action Request System 7. shorten the time to 5 minutes: ARSystemServerName.MAPI_Sent_Folder= folderName ARSystemServer is the name of the AR System server associated with the Email Engine. Changing the form entry interval time When the Email Engine starts. For example. set the polling parameter. To shorten the default time interval in the EmailDaemon. add the following line to the EmailDaemon. folderName is the name of the folder that stores the outgoing notification emails. stop and restart the Email Engine.properties file: ARSystemServer.properties file.Interval = 5 For more information about this property or the EmailDaemon. Every 30 minutes. If you have changed the value of this field. the Email Engine automatically queries the form for changes to the form entries and updates the information.04 Saving outgoing notifications in MAPI If you use the MAPI email protocol and you want to save messages on the Exchange server. you must restart the Email Engine for the change to take effect. see “Performance and configuration settings” on page 182. 44 BMC Remedy Email Engine Guide . enter Sent Items to save messages to your Sent Items folder in Microsoft Outlook.6. To save outgoing notifications. you must configure your outgoing mailbox to save outgoing notification emails in an Outlook folder. Chapter 2 Configuring Email Engine mailboxes 45 . There is no “one size fits all” CA solution. what CA to use. This section explains in general terms how to configure the Secure Sockets Layer (SSL) for use with Email Engine.Configuring SSL for the Email Engine Configuring SSL for the Email Engine Enterprise and stand-alone certification authorities (CAs) can issue certificates for secure email by using SSL. while a cert issued by an in-house CA is not trusted by anyone outside the organization. for example. 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. The primary difference between a commercial or in-house CA is that a “cert” (certificate) issued by VeriSign is trusted far and wide. You must decide whether to use a commercial CA (for example. 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. 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. Configuration differs considerably between using a commercial CA authority like VeriSign and using a certificate server in a non-active directory environment using Microsoft’s Certification Authority management console. You must consider various factors when using SSL. For the detailed procedure. With a local CA. you can retrieve and install the cert using a browser. 46 BMC Remedy Email Engine Guide . a Use the Certificate Wizard to generate a cert request. but not encrypted. return the properties for the IMAP virtual server. The procedures required to submit and receive a cert from a CA vary. depending on the CA. generate a personal certificate that users will use for signing and encrypting their 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. between the two users. c Send email messages that are signed. For more information. see “To add an SSL certificate to a Microsoft Exchange server” on page 49.6. c Use the Certificate Wizard to install the cert received from the CA. b Submit the cert request to the CA. For more information. see “To create a CA certificate from a CSR” on page 48. see “To generate a Certificate Signing Request (CSR) for a Microsoft Exchange server” on page 47. 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. 3 Make sure that email users obtain their own certificate.04 2 In Microsoft Exchange System Manager (used by a Microsoft Exchange system administrator only). a Through the CA.BMC Remedy Action Request System 7. expand Servers > the appropriate server name > Protocols > IMAP4. enter a unique name for the certificate. 3 On the Web Server Certificate Wizard: a On the first page. To generate a Certificate Signing Request (CSR) for a Microsoft Exchange server 1 In Microsoft Exchange System Manager. open the Access tab. do not select the Server Gated Cryptography (SGC) certificate check box. 2 On the Default IMAP4 Virtual Server Properties dialog. If you plan to install the trial certificate from VeriSign. c On the Name and Security Settings page. and click Next. and click Next.Configuring SSL for the Email Engine 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. select Create a new certificate if you have not yet created an SSL certificate for your web server. b On the Server Certificate page. select Assign an existing certificate. and click Next. For more information about SGC. 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. and click the Certificate button. select 1024 as the bit length. select the appropriate certificate and generate a CA from the CSR. Chapter 2 Configuring Email Engine mailboxes 47 . The same procedure applies to POP3 and SMTP. A list of the existing SSL certificates installed on your web server appears. If you already have an SSL certificate for your web server. click Next. and select Default IMAP4 Virtual Console. see your CA documentation on SSL algorithms. 4 Upon completing the steps.” 6 Save the file with the . . certreq. click Back to navigate to the appropriate pages and change the necessary values. for example.cer extension. enter the common name for your site.com/prod/srv/trial/ step1. otherwise the CA would create the SSL certificate successfully. This name will also be used to configure SSL on Outlook Express. To create a CA certificate from a CSR 1 Open a browser and navigate to https://www.html. h On the Request File Summary page. You can access the Microsoft Exchange server with this common name.. a certificate is generated and sent to the email address that you entered in your information form.6.txt file in the appropriate text area.BMC Remedy Action Request System 7. and City/locality. Otherwise. State/province. -----End Certificate----- Make sure that you do not select blank lines or spaces before “-----Begin Certificate-----”and after “-----End Certificate-----.verisign. and click Next..txt). copy the contents of certreq. and click Next. i On the final page. 48 BMC Remedy Email Engine Guide . enter the absolute path and file name for the CSR (for example. e On the Your Site’s Common Name page. select the appropriate Country/Region. Do not enter an IP address as the common name. and click Next. g One the Certificate Request File Name page. 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> . 3 When prompted for the CSR.cer... select an Organization and the Organizational unit. 2 Enter the information required to create the trial SSL certificate.04 d On the Organization Information page. f On the Geographical Information page. and click Next if the information is accurate. Make sure that you provide a location that is easy to remember and access. web. verify the information you provided so far. click Finish to complete the process and close the wizard. To set up Microsoft Outlook Express and Email Engine 1 To use IMAPS (IMAP over SSL) for Outlook Express. and click Next. you must provide the “common name” you entered while creating the CSR.verisign. Email Engine uses the location where Oracle Java Runtime Environment (Oracle JRE) is installed as the keystore path. NOTE Find the appropriate keystore path before entering the command. If you plan to install the trial certificate from VeriSign.cer javaHome is the directory where JRE (not JDK) is installed. and select Default IMAP4 Virtual Console. the “CN does not match with passed value” warning appears. 2 On the Default IMAP4 Virtual Server Properties dialog. and click the Certificate button. 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.html. open the Access tab. and select Default IMAP4 Virtual Console. expand Servers > the appropriate server name > Protocols > IMAP4. Follow the prompts on the screen and install the test root CA on the computer where you want to configure Outlook Express. expand Servers > the appropriate server name > Protocols > IMAP4. open the Access tab. To enable SSL communication on a Microsoft Exchange server 1 In Microsoft Exchange System Manager. b On the Pending Certificate Request page. When prompted to enter the IMAP server address. 2 To configure Email Engine to use SSL. c On the Process a Pending Request page. and click Next.Configuring SSL for the Email Engine To add an SSL certificate to a Microsoft Exchange server 1 In Microsoft Exchange System Manager. 2 On the Default IMAP4 Virtual Server Properties dialog. click Next.com/products-services/security-services/ssl/ buy-ssl-certificates/free-trial/test-root-ca/trialcainstall. and click OK. Chapter 2 Configuring Email Engine mailboxes 49 . 3 On the Web Server Certificate Wizard: a On the first page. 3 On the Security dialog. If you provide any other value or an IP address. do not select Require 128-bit encryption. and click the Communication button. select Require secure channel. open a browser and navigate to http://www. select Process the pending request and install the certificate. enter the absolute path and file name that you provided when creating the CSR. 04 50 BMC Remedy Email Engine Guide .BMC Remedy Action Request System 7.6. 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 .Chapter 3 Outgoing email This chapter provides information and instructions for creating and transmitting outgoing email messages from the Email Engine. 52 BMC Remedy Email Engine Guide . the AR System server triggers an escalation. John. As a result. Step 1 In the XYZ Company. Because of a sudden swell of incoming tickets.BMC Remedy Action Request System 7.04 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 Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst 1 AR System admin defines SLA 2 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 4 User receives urgent ticket assigned to him Bob Backline In this scenario. the local AR System administrator. the IT department has a service-level agreement (SLA) that urgent HD incident tickets must have a response in one hour. the front line engineers cannot respond to one of the urgent request in one hour. has decided to test the notification capabilities of the Email Engine.6. 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. and so on). Step 4 Bob’s email client receives the new email. AR System uses the Email Engine to send all notifications. templates. see “Using notifications” on page 54. 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. The Email Engine monitors the AR System Email Messages form for all outgoing messages. short description. Chapter 3 Outgoing email 53 . query results. “Using email templates. For more information. aliases. the Email Engine ignores any other text. This message consists of the field values from the HD Incident form (submitter. and special keyword syntax as message content. the back line Customer Support engineer. For more information. Bob sees that all the necessary details of the ticket are contained in the email constructed by the Email Engine. one crucial task you performed was associating an outgoing mailbox. variables. Most importantly.” This section describes the different types of outgoing email in the Email Engine: Notifications—The most important use of outgoing email is using workflow to send notifications to users. for example. For more information. You must install the Email Engine to send notifications from the AR System server. For more information. The Email Engine then transmits the message to the mail server with instructions to notify Bob Backline. specifically for the purpose of replying to emails that require a response. see the detailed reference material and examples of their use in Chapter 5. He reads that an urgent ticket has been assigned to him. when the escalation is triggered. and then sends the messages to the outgoing mailbox on the mail server. Replies to senders—A common function of outgoing email is making replies to senders (who send email to the incoming mailbox) with results. assignee. Step 3 The Email Engine constructs the message according to formatting instructions contained in the Outgoing Mailbox it is using. the AR System server creates an outgoing record in the AR System Email Messages form. When you created an incoming mailbox. its urgent status.Using outgoing email Step 2 Because John has configured the Notify escalation to use email as the notification mechanism. see “Sending reply email: Giving a professional look to outgoing email” on page 89. not just email. 04 Messages form—You can send outgoing email using the AR System Email Messages form. 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 BMC Remedy Email Engine Guide . users can then click a URL to open the ticket in a browser and view additional details about the ticket. or specify contents templates to use in the body of the email. The average user never sees or needs this form. One major benefit of the Email Engine is the ability to notify users with a professional-looking HTML-formatted email. For more information. Figure 3-2 illustrates a notification that a ticket was created and sent to a user. you only use the AR System Email Messages form for configuring or troubleshooting the Email Engine. In the notification email. not just email. Using notifications The most important use of the Email Engine is sending notifications to users because AR System uses it to send all notifications. Typically. You must install the Email Engine to send notifications from the AR System server.BMC Remedy Action Request System 7. You can type the message. see “Using the Email Messages form to send outgoing email” on page 74.6. as shown in Figure 3-3 on page 56). this shortcut provides a link to the entry on the AR System server) To send email notifications. The Email Engine then picks up the entries from the form. Defining workflow to send email notifications When the filter or escalation is triggered (for example. point to the AR System server you intend to use. The Email Engine can be installed on a separate server from the AR System server processing the workflow. from a filter submit or modify action. For more information about using filter or escalation workflow. optionally.Using notifications If you choose Email as the delivery mechanism when creating a Notify filter or escalation. Chapter 3 Outgoing email 55 . processes them. field contents) on the AR System Email Messages form. the AR System server logs a message containing the notification text (and. see the Form and Application Objects Guide. When you install Email Engine. and sends the email notifications to the designated user or group. 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. This is because there is no Request ID with join forms during a Submit operation. NOTE If you create notifications using the Submit execute condition with join forms. you must install the Email Engine. a shortcut is as an attachment to the email notification. the fields returned in the notification message will not be populated. you will not receive any notifications.6. The Notify Filter (or escalation) page of the Create Filter (or escalation) dialog box is displayed. see Chapter 2. Otherwise. For more information. For more information. This webcast includes . see the Education link at http://www. you can select Email as a notification mechanism.def and data files you can download and modify for your own use.BMC Remedy Action Request System 7. and Templates—that are used to define the configuration and contents of your email message. TIP This section borrows from the Email Engine: Administering (Webcast) available from BMC Remedy Education Services. When you select Email. Messages. The Email Engine must be running to enable you to send email notifications.” 2 Create your Notification filter or escalation. the bottom part of the window displays three tabs—Fields. 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.com. select Notify. “Configuring Email Engine mailboxes. 3 Click the If Action tab or the Else Action tab.04 Figure 3-3: The Filter window In a Notify action from filter or escalation workflow (see Figure 3-4 on page 57). To define workflow to send email 1 Make sure that you have an outgoing mailbox configured with Default Outgoing Mailbox set to Yes. 4 From the New Action list. The fields required to define the Notify filter or escalation appear. 56 BMC Remedy Email Engine Guide . or set Mailbox Name in the workflow to the configured outgoing mailbox.bmc. Using notifications Figure 3-4: The Notify filter or escalation action 5 In the Text field. The field or keyword will be expanded when the notification is sent. <a href="http://polycarp/arsys/servlet/ ViewFormServlet?server=polycarp&form=HD+Incident&eid=$Request ID$">$Request ID$</a>. has been assigned to you. You can include sophisticated AR System functionality in the text of an email notification. Chapter 3 Outgoing email 57 . enter the text of the message. You can use the Text list to insert fields from the current form or keywords into the text. to a maximum of 32 KB. “URLs for forms and applications. see the BMC Remedy Mid Tier Guide.” page 76. The $Impact$ incident. 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. Figure 3-5 demonstrates the use of a URL that performs a search that goes directly to the request the user needs to view. 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. emails are sent out from the Email Engine in the order they were received. For more information. If the contents of the User Name field do not match an existing User or Group definition. or POP mail protocols. By default. The order in which these entries appear is the order in which the Email Engine searches for addresses.04 6 In the User Name field. Joe. and Templates tabs are activated. $USER$@acme. You can enter a maximum of 255 characters. WARNING Do not use group notifications as an email system for broadcast type items because the server processes a notification for each member. select Email. an alias for a group. ranges of 1 to 10 are acceptable.com). 8 To set properties in the EmailDaemon. IMAP. 9 From the Mechanism field. or an email address representing a program. 58 BMC Remedy Email Engine Guide . an entry is made in the AR System Email Messages form (see Figure 3-9 on page 62).com) or a keyword (for example. see “Performance and configuration settings” on page 182. For each recipient. 10 Select the Add Shortcut check box to include the originating request as an ARTask attachment in the email that is sent. 7 Enter a value in the Priority field. enter the name of the users or groups to notify. This address can be an email address representing users who are not using AR System.properties file so that the Email Engine sends high-priority emails first and then lower priority emails. the system interprets the field contents as a literal address and sends the notification to that address by SMTP. see “Defining fields in email notifications” on page 59 and “Using the Messages and Templates tabs” on page 61. The Fields.6.BMC Remedy Action Request System 7. MAPI. If you are using a field reference (for example. 11 Save the filter or escalation. $Submitter$). change the following property as shown: SortMessages=true For more information about using the EmailDaemon. not in the order of priority. Messages. To specify one or more recipients. An email alias is more efficient.User@acme. do not include the domain name as part of the notification because the email address is being read from the Email Address field of the user’s entry in the User form.properties file. The options are: None—None of the fields is included with the notification.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. The field or keyword will be expanded when the notification is sent. Selected—Selected fields from the fields list are included with the notification. All—All of the fields in the request are included with the notification. if an administrator selected All. Chapter 3 Outgoing email 59 . NOTE The Request ID of entries from display or vendor forms are not returned in notifications. You can enter a maximum of 255 characters. only the fields in the template appear in the email. for example. Changed—Only fields that have changed in the current transaction are included with the notification. If you enter a field name in the Subject Line field. the notification will contain the value of the field in the database. $USER$. but the template only uses a few fields. NOTE If you use a content template to format the email. Subject text can include the use of keywords. the template will override any of the options that are selected. 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. 2 Select which fields have the content you want to select in the email (in addition to the notification text). For example. see “Variables” on page 156.6. footer. the message status changes in the Email Messages form from Yes to Sent. 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.BMC Remedy Action Request System 7. To receive the attachment. The order of fields included in the notification is still based on their actual X and Y coordinates in the form. and content templates are selected in the Include Fields list of the filter. See the Form and Application Objects Guide. Figure 3-7 shows that this notification will be sent to the ticket assignee ($Assigned To$). select the attachment fields from the Fields list. 3 To include attachments in an email notification. If you chose to delete Notification messages in your mailbox configuration. the notification email entry is deleted from the BMC Remedy Email Messages form. “Defining access control. which the AR System administrator defines when the field is created. Using their X and Y coordinates. The order of fields included in an email notification is strictly based upon their arrangement in the form view. then down (in a zigzag-like pattern).” page 21.) To be able to send the field contents. If a form includes page fields. the $Assigned To$ group must have permission to the field. Fields excluded from the form’s default view are randomly included at the bottom of the list.04 Make sure that all fields used as variables in header. the order of fields begins top left to right. After the notifications are sent. (For more information.) 60 BMC Remedy Email Engine Guide . make sure that users being notified have the necessary permissions. (See “Deleting email notifications” on page 70. the pages are ignored. the settings relating to the mailbox entered in the Mailbox Name field apply. which templates to use. If you leave these fields blank. enter the name of the outgoing mailbox that you want to handle the notifications if you do not want to use the default mailbox. If you leave these fields blank. You can use a field or a keyword to substitute the mailbox name. the values in your notification email default to your current mailbox configuration settings. Any entries in the fields in the Messages and Templates tabs will override the default settings. Or.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. an error message will be generated. or you can specify another mailbox in the AR System Email Mailbox Configuration form. To define the Messages tab 1 In the Mailbox Name field. The fields in these tabs are optional. If there are no entries in the Messages and Templates tabs. which mailbox to use. This mailbox name should correspond to a valid mailbox configured in the AR System Email Mailbox Configuration form. if the Mailbox Name field is empty. and no default mailbox exists. The default outgoing mailbox is the first mailbox created. Chapter 3 Outgoing email 61 . the default outgoing mailbox settings apply. Figure 3-8: The Notify filter or escalation dialog—Messages tab Defining messages in email notifications Use the Messages tab to override your mailbox configuration settings for the Notify action. and so on. The maximum size of these fields is 255 characters.04 2 Enter information in the From. a specified mailbox. CC. or a default mailbox that has already been configured).com). A field A keyword The order in which these entries appear is the order in which the Email Engine searches for addresses. separate the entries by hard returns. 3 In the From field. the Email Engine populates the equivalent fields in the AR System Email Messages form for the appropriate User Name (Figure 3-9). If you fill in these fields. $USER$@acme. 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. enter the name to be displayed to indicate where the mail is from.6. you need to display and save the AR System Email Messages form before you see the entries.User@acme. or for the default mailbox. Figure 3-9: The AR System Email Messages form However. 62 BMC Remedy Email Engine Guide . Joe.com) or a keyword (for example. Reply To. You can use the following entries in the fields: AR System user logins AR System groups Email addresses—Include the email domain name if you are entering a user’s name (for example.BMC Remedy Action Request System 7. there will be no entry in the email to indicate who the email is from. and BCC fields: If you make multiple entries in these fields. 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. 5 In the CC and BCC fields. or for the default mailbox. especially if you list a group name with some ambiguity about which is the first name on the list. 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. the values in your notification email default to your current mailbox configuration settings. 6 In the Organization field. no copies of the email will be sent. or a field reference to a name that you would like to appear on the email. 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.Impact' = "Urgent") AND ( 'Impact' != 'DB. Chapter 3 Outgoing email 63 . enter a company name. a keyword. This might be a security issue. Defining templates in email notifications Use the Templates tab to define any templates to use in the email. If this field is blank. 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. a reply will be sent to all the names in the group.Impact') AND ( 'Assigned To' = $NULL$ )). 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.Using notifications 4 In the Reply To field. The permissions applied to the recipients of the CC and BCC fields will be the same as those of this first listed user. You could create workflow that substitutes a specially designed urgent template to alert a manager to the email’s importance. if you enter a group name. If you leave these fields blank. You might list names individually in the User Name field so that you have more control over the permission status. there will be no entry in the email to indicate any Reply To. If you specify multiple recipients in the User Name field (see Figure 3-4 on page 57). an organization. To define the Templates tab 1 In the Header. By default.6. workflow would substitute a value that uses the Urgent header template instead. specify the names of the templates to use for a header.04 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. The templates specified here must be stored in the AR System Email Templates form. a notification would use a default header template. For more information. You can enter the name of the template directly. a filter could read a value from a hidden field on a form. and the name must be the same as that entered in the Template Name field of the AR System Email Templates form. But if a ticket was marked Urgent. content. 64 BMC Remedy Email Engine Guide . see “Dynamically assigning templates to outgoing email” on page 66. or enter a field reference or keyword that leads indirectly to a template name.BMC Remedy Action Request System 7. Content. For example. and Footer fields. or footer of the email notification. and save your changes to the filter or escalation. the variable format must correspond to a field’s database name and not the field label. 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.” When you create a content template for email notifications.Using notifications Figure 3-11: The Notify filter or escalation dialog—Templates tab For more information about creating and using templates.TIME$$# These formats are based on AR System core field ID 7.) Chapter 3 Outgoing email 65 . (See Figure 3-8 on page 61. 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.Closed. The Status History strings shown here as examples could also be displayed languages other than English. 2 Click Add Action. see Chapter 5.New. If you are using a content template for email notifications and you want to see the notification text in the corresponding email. NOTE You cannot use AR System keywords in content templates for outgoing emails in notifications.USER$$# #$$Status History. represent the Status History in the following formats: #$$Status History. “Using email templates. The system determines which templates to use in the following order: a The template entries in this tab. Table 3-1: The header template to use for an incident based on the impact Impact Urgent High Medium Low Template Name Header_Urgent. content.04 c The templates set as defaults for the default mailbox. the order of fields included in an email notification is strictly based upon their arrangement in the form view.” you can see them using workflow. If no template is used for the Content. 66 BMC Remedy Email Engine Guide . Fields excluded from the form’s default view are randomly included at the bottom of the list.htm Header_Medium. medium. d No templates are used.6. 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 Notify filter and escalation action integrates with Email Engine templates. If a form includes page fields. The templates are designed so that technicians can quickly tell if an incident’s impact is urgent. high. Using their X and Y coordinates. The Email Engine then uses templates stored in this form to format outgoing email. then down (in a zigzag pattern). 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. allowing dynamic template assignment. You could also dynamically assign templates through workflow. and footer templates. the order of fields begins top left to right. The order of fields included in the notification is still based on their X and Y coordinates in the form.BMC Remedy Action Request System 7.htm Header_Low. the pages are ignored. you can hard-code these templates by using the template name.htm Header_High.htm You can create a data-driven approach to dynamically assign the correct template for the appropriate impact. or low. With templates stored as “data in a form. The Templates tab of the Notify action allows you to assign header. As demonstrated in “Defining templates in email notifications” on page 63. selecting the proper value for the Template Name field. Four records are created—one for each of the impact values. your users have their own email mailboxes set up. Figure 3-12 illustrates that the Urgent impact type uses the Header_Urgent. 4 (Optional) Attach a character field search menu that queries the AR System Email Templates form as a further enhancement. 2 Add a selection field to the XYZ Templates form. High. the Impact selection field attributes are used—Low. and Urgent. 5 Log in to BMC Remedy User and open the XYZ Templates form in New mode. Template Name) to store the value of the template to be used. 6 Create the records for each Impact type. XYZ Templates).Using notifications The following procedure assumes your Email Engine is properly configured. 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.html template. and you have created and stored your templates. In this example. This field should use the same attributes you plan to use to determine template assignment. 3 Create a character field (for example. Chapter 3 Outgoing email 67 . Medium. 8 Add a hidden character field (for example.04 Figure 3-12: Template records 7 Create a regular form (for example. Header Template) to the XYZ Incident form (Figure 3-13).6. This field stores the name of the header template to be used with each incident when it is created or modified. XYZ Incidents).BMC Remedy Action Request System 7. Figure 3-13: A form with hidden fields Hidden fields to store templates 68 BMC Remedy Email Engine Guide . This workflow will also create an email notification with the proper header template dynamically assigned based on its impact level. With this workflow. b Select Submit and Modify as the execute conditions. and so on. relevant text (including request ID of the ticket). $Submitter$ as the user name. When Joe User opens his email client.Impact' != $NULL$ as the Run If qualification. Here you define the filter to query the XYZ Templates form created earlier where ‘Impact’ = $Impact$. when the filter detects there is a new transaction value in the Impact field). The filter workflow executes and creates a new ticket. Here you want the filter to fire on Submit or Modify whenever the value of the Impact field changes (that is. for example. the name of the proper template. he receives the following email: Chapter 3 Outgoing email 69 . create a Set Fields action with the following parameters: a Read the value for the field from the XYZ_Templates form. 10 In the If Action tab. create a Notify action. c Select Header Template as the field name and $Template Name$ as its value. b Enter other parameters as needed. is stored with each incident. a Place the variable $Header Template$ in the Header field. c Enter 'TR. b Enter 'Impact' = $Impact$ as the Set Fields If qualification. for Joe User) and assign it an urgent value. a In the Basic tab. based on its impact. create a new ticket (for example. The result of this filter is data-driven automatic template assignment workflow. 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. select XYZ_Incidents as the form. 12 In the XYZ Incidents form.Using notifications 9 Create a filter to set the value for the Header Template field on the XYZ Incident form. Email notifications do not go through this client transition. the data in the notification is in the same format as that stored on AR System server. This default setting reduces the number of records stored in your message form. For more information. therefore. the decimal separator is displayed as a comma. This might result in incorrect date/time and numeric values being displayed in a notification to different locales. date/time or numeric values stored on the AR System server have a decimal separator. see “Submitting requests across different time zones” on page 208. 70 BMC Remedy Email Engine Guide .04 Figure 3-14: An email notification with the Urgent header template You could enhance this with a content template used specially for urgent tickets. you can configure your email system to automatically delete notification messages from the AR System Email Messages form after they have been successfully sent. the format for numeric and date/time data might change to accommodate the client locale. but when this data is relayed to a German client.6.BMC Remedy Action Request System 7. Displaying date/time or numeric values in email notifications When the AR System server sends data to a client with a different locale. For example. Deleting email notifications Using the AR System Email Mailbox Configuration form. with email generated from notification actions or escalations. in creating an outgoing email. outgoing email is formatted correctly. unless you are using email templates to modify records. Figure 3-15: Option to delete outgoing notification messages 2 Set the Delete Outgoing Notification Messages field to Yes. When you first start using the Email Engine. 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. see “Sending reply email: Giving a professional look to outgoing email” on page 89. open the entry of your outgoing mailbox. A mail template exported with BMC Remedy Developer Studio lists all the available field labels you could use. for example. you will use the AR System Email Messages form for troubleshooting the Email Engine. For information. If you configure the system to delete messages automatically. your server can quickly fill up with email notifications. and so on. NOTE Replies to incoming email are not discussed in this section. you should automatically delete email notifications. and click the Advanced Configuration tab. see “Advanced outgoing mailbox configuration” on page 30. the Email Engine will not permit you to modify records. But after your Email Engine is running correctly. you might not want notifications automatically deleted to make sure they are sent to the expected users. 3 Save your changes. Chapter 3 Outgoing email 71 .Using notifications TIP Most of the time. To delete email notifications 1 In the AR System Email Mailbox Configuration form. otherwise. Using templates with outgoing email Email templates can help you with outgoing mail from the Email Engine. for example. For more information about configuring the email system. 0.BMC Remedy Action Request System 7. core fields are replaced with their actual values in the email that is sent out.New. You use the following syntax with form fields: #$$DatabaseNameOfField$$# Content templates used with notifications or escalations cannot contain the following information: Keywords—Keyword substitution in content templates is not implemented in Email Engine 7. 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. #$$536870925$$# is incorrect.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 .04 You can use content templates with notifications or escalations to arrange the fields and values of the entry that triggered the notification.USER$$# StatHist-Time:#$$Status History. you should use #$$Id_Integer$$# where Id_Integer is the database name of the field.00 and later. As a result. the #$$AR Notification Text$$# variable is replaced by the text entered in the Text Field of Notification group in BMC Remedy Developer Studio. As a result. Content templates used with notifications or escalations can contain the following information: Plain text Variables For example. Field IDs—Field IDs are not substituted with entry values.New. Instead. $USER$ or $DATABASE$ in a content template will not be replaced with actual values.6. Core fields For example. 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. Editor.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.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> Chapter 3 Outgoing email 73 . as shown in the following example: <?xml version="1.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.0"> <meta name="ProgId" content="FrontPage.Document"> <title>Lighthouse</title> </head> <body> <p><font face="Arial Black"> #$$AR Notification Text$$# </font></ p> <p><img border="0" src=". HTML outgoing content templates can contain graphic images. charset=windows-1252"> <meta name="GENERATOR" content="Microsoft FrontPage 4. 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./images/lighthouse. or specify content templates to use in the body of the email.BMC Remedy Action Request System 7. substitute variables. you can use a template. Figure 3-16: AR System Email Messages form You can type the message. From the Advanced Options tab.) WARNING When sending HTML messages. or an alternate attachment as your body content. as shown in Figure 3-16. any content in Plain Text Body tab is ignored. To send email from the Email Engine. To send plain text messages. 74 BMC Remedy Email Engine Guide . make sure that all the required content is in the Plain Text Body tab and that the HTML Body tab is empty.04 <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. see “Displaying advanced options for outgoing email” on page 81. You can include attachments with your email using the Attachments tab.6. you must use a specific label/value pair syntax along with the Action label in the body of the email. (For information. submissions. “URLs for opening forms and applications.Using the Email Messages form to send outgoing email Sending outgoing email in plain text You can use the Email Engine to send outgoing email in plain text. unless overridden by entries in the AR System Email Messages form.” page 76. Chapter 3 Outgoing email 75 . For more information. 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. or modifications to entries contained on your AR System server. 2 From the Mailbox Name menu. see “Configuring outgoing mailboxes” on page 28. These emails can be formatted using templates that specify the layout of a message in plain text. If you leave this field empty. or XML. HTML. (For more information. use this syntax: http://hostName/arsys/forms/serverName/formName. Plain text email can include the results of queries. the default outgoing mailbox will be used. see the BMC Remedy Mid Tier Guide.) 3 Select Outgoing from the Message Type list. 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. Figure 3-17: AR System Email Messages form (displayed in browser) TIP To view the AR System Email Messages form in a browser. There are no syntax requirements for typing “plain” text in your outgoing message.. see “Including attachments with outgoing email” on page 79. for example. Organization. “Using email templates. 6 Optionally. You can override these settings here. 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. Table 3-2: Email Engine priorities mapped to Microsoft Outlook priorities Email Engine Priority 0 1 2 3 4 . For more information.. Low importance By default. b Enter other information as needed.04 4 Click the Message tab and fill in the header information. 7 Click the Plain Text Body tab and enter your message text. Use the following properties: To ignore priority (default): SortMessages=false To use the priority: SortMessages=true For more information about using the EmailDaemon.. see Chapter 5.properties file for the Email Engine to send high priority emails first and then lower priority in that order. 76 BMC Remedy Email Engine Guide . 5 Enter a subject line for your email in the Subject field. emails are sent out from the Email Engine in the order they were received.properties file. not in the order of priority. The From.. Use the following table to determine what value to use in the email message within AR System to get the desired Microsoft Outlook priority. enter the name of the user you are sending the email to. see “Performance and configuration settings” on page 182. any label/value pairs that you include must follow their specific syntax. a In the To field.BMC Remedy Action Request System 7. 100 Microsoft Outlook Priority Normal High importance High importance Normal (default) Low importance . But you can set properties in the EmailDaemon. an organization. To.” To add an attachment. CC. Reply To. enter a priority number between 1 to 100 in the Priority field. However.6. submissions. or modifications to entries contained on your AR System server. 8 Click Send to send the mail from the outgoing mailbox to the user. or using a template. These emails can be formatted using templates that specify the layout in plain text.Using the Email Messages form to send outgoing email To send the email with a template other than the default templates for the specified mailbox. Sending outgoing email in HTML You can use the Email Engine to send outgoing email messages that include the results of queries. or XML. 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. see “Using the Email Messages form to send outgoing email” on page 74. For sample contents of an outgoing message. For more information. 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. 2 Click the HTML Body tab. To send outgoing messages in HTML 1 Open the AR System Email Messages form in New mode to create an outgoing message. “Using email templates. HTML. see Chapter 5. 3 Enter HTML content. see “Using the Variable Replacement tab” on page 83.” Chapter 3 Outgoing email 77 . Radio buttons—Users modify the status by selecting an input type Radio control field.04 For how to define HTML. especially input type controls. When the user enters their password. see any standard HTML reference book or reputable online source (http://www.org/).w3.BMC Remedy Action Request System 7. They can select only one radio button option. as shown in Figure 3-19.6. The Email Engine generates the email. the text is masked. Figure 3-19: A Password field with encryption Text input fields—Users modify the contents of the Assigned To and Short Description fields by using text input fields. asterisks appear instead of the typed symbols or letters. this HTML message includes a Password control field as an input type. as shown in Figure 3-18. 78 BMC Remedy Email Engine Guide . 4 Click Send to send the mail from the outgoing mailbox to the user. Figure 3-18: An outgoing email in the HTML format This outgoing email contains the following HTML input features: Password control field—Users become nervous about sending passwords in clear text. For security. Additional HTML examples are demonstrated in “Sending modify instructions in HTML” on page 122. It also stores attachments for templates. 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. see “User-defined HTML or XML text in outgoing HTML emails” on page 102. click the Attachments tab (Figure 3-20 on page 79). such as a graphic for an HTML template.Using the Email Messages form to send outgoing email For information about encoding user-defined markup text in outgoing email messages. The AR System Email Attachments form (see Figure 3-21 on page 80) stores attachments for incoming and outgoing emails. To add attachments to your email 1 In the AR System Email Messages form. NOTE Having a large number of records in the email messages and email attachment forms might degrade the performance of the Email Engine. The system associates the attachment with a specific email in the AR System Email Association form. Figure 3-20: The AR System Email Messages form—Attachments tab Chapter 3 Outgoing email 79 . 7 Enter a name for the Attachment in the Attachment Name field. To change the name: a Select the item in the attachment pool.04 2 Click Add Attachment to open the AR System Email Attachments form (Figure 3- 21).: b Edit the file name as needed. 8 Click Save. The system will assign the association a unique ID. The Add Attachment dialog box appears. the email and the attachment are associated through the AR System Email Association form. 80 BMC Remedy Email Engine Guide . click the arrow next to the blank field at the bottom of the pane. 6 Click Open. If you are using a Windows system.BMC Remedy Action Request System 7. 2 Select the attachment. you can also drag and drop a file into the attachment pool. and click the edit button in the Attachment Name field.6. Your attachment is added to the list in the attachment pool. The file is added to the list of attachments. When you send or save your email. To add previously saved attachments to email 1 In the Attachments tab of the AR System Email Messages form. 4 Right-click in the attachment pool and choose Add from the menu. If you do not specify a name. 5 Browse to the file you want to add and select it. Figure 3-21: The AR System Email Attachments form Attachment pool 3 Select Email from the Type list. 3 Click the Add Existing button. The name of the attachment is displayed in the Attachment Name field. the system will see the attachment by its file name and location. and Errors tabs. You can also modify the Attachment Name. The attachment is deleted from the list. You can also view information and errors of the outgoing message. 5 Click the Refresh Table button to refresh the table in the Attachments tab of the AR System Email Messages form. Deleting an attachment Use the following procedure to delete attachments in outgoing email. Displaying advanced options for outgoing email For outgoing messages. To delete attachments 1 Click the Attachments tab in the AR System Email Messages form. Message Information. or Errors. 3 Click Delete Attachment to open the AR System Email Association form. To display the Advanced Options. 5 Modify the attachment as required. perform the following tasks: To display advanced options 1 Create an outgoing message. 2 Select the attachment you want to modify. 3 Click the Modify Attachment button to open the AR System Email Attachments form. To modify attachments 1 Click the Attachments tab in the AR System Email Messages form. 2 Select the attachment you want to delete. you can include advanced options like replacing variables. Message Information. 6 Click Save to save your modification. 4 Close this form.Using the Email Messages form to send outgoing email Modifying an attachment Use the following procedure to modify attachments in outgoing email. 4 Click Search to locate the attachment. 2 Select Yes in the Display Advanced Options field of the AR System Email Message form. The attachment appears on the attachment list. Chapter 3 Outgoing email 81 . 3 Select one of the advanced option tabs: Advanced Options. The content can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. or it uses the default mailbox and its settings if no Mailbox Name is entered. add variables.6. For information about configuring your outgoing mailbox. You can create these templates in a text editor or export them using BMC Remedy Developer Studio. 3 Select templates from the relevant menu lists. You can also specify actions to be performed when the Email Engine parses contents of the email. 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 system uses the default templates for the mailbox in the Mailbox Name field. If header and footer templates are specified in content templates as a label/value pair. they will be applied to the email reply. or enter the name of a template as defined in the AR System Email Templates form. The content template can also contain formatting instructions. and then click the Templates tab. or the default mailbox. display the advanced options. see “Configuring outgoing mailboxes” on page 28. 82 BMC Remedy Email Engine Guide . To add templates to outgoing email 1 In the outgoing message. All the templates you use here must be previously stored in the AR System Email Templates form. The template specified here will override those configured for the specified mailbox. or use alternative attachments.04 Advanced Options tab The Advanced Options tab lets you replace templates. If you leave Template fields blank. Header and footer templates are used to place lines of text or graphics on an outgoing message. 2 Click the Advanced Options tab. Using the Templates tab The Templates tab enables you to include a content.BMC Remedy Action Request System 7. header. Figure 3-23: The AR System Email Messages form—Advanced Options.Using the Email Messages form to send outgoing email Figure 3-22: The AR System Email Messages form—Advanced Options. This applies only to the specific outgoing email and the templates specified in the Templates tab. 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. Variable Replacement tab Chapter 3 Outgoing email 83 . as shown in Figure 3-23. the Field Values field of the Variable Replacement tab is populated with the database name of the field and its value in the entry. 84 BMC Remedy Email Engine Guide . For example. So. 6 Select a content template.BMC Remedy Action Request System 7. 8 Enter a value for a variable in the template in the Field Values field.6. This value will then be substituted for the variable when the outgoing email is sent. 5 Click the Templates tab. and a substitution is made accordingly.04 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. 3 Enter Yes in the Display Advanced Options field. For example. 2 Fill in header information. 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$$#$$]. 4 Click the Advanced Options tab. 7 Click the Variable Replacement tab. 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. make sure to use the exact database name in the content template delimited by #$$…$$#. When an entry is created in the Email Messages form for the outgoing message. This database name is matched with the database name that is specified within #$$…$$# in the content template. To replace a field value using a variable replacement 1 Create an outgoing message. you can specify the form name and qualification criteria. In the same tab. the qualification criteria is evaluated. As a result. 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. then you can use the field ID in the Field Values field of the Variable Replacement tab. and the values of the entries are substituted for the field IDs in the Field Values field. This action will be specified in a Content template. entries that match the criteria are retrieved. The Email Engine searches the specified form for the record. Variable Replacement tab 13 Send the outgoing email. when the outgoing email is sent. Chapter 3 Outgoing email 85 . 11 Enter any access information necessary in the AR System Server TCP Port field and the AR System Server RPC Number field. Figure 3-24: The AR System Email Messages form—Advanced Options. If a template is specified in the Templates tab and the template contains field IDs.Using the Email Messages form to send outgoing email If you create an outgoing email from the Email Messages form instead of using a notification or escalation. 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). 10 Enter the name of the AR System form to which these values apply. 9 Enter the name of the server on which the form resides. 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). The contents of the attachment appear in the body of the email.04 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$$#$$]. instead of typing it into the Body field in the Message tab. Attachment Alternatives Attachment field (for example. but using the Variable Replacement feature allows more flexibility. HTML) Attachment pool The Attachment Alternatives tab enables you to add the content of your email as a plain text or HTML attachment. 86 BMC Remedy Email Engine Guide .BMC Remedy Action Request System 7.6. Using the Attachment Alternatives tab Figure 3-26: The AR System Email Messages form—Advanced Options. For example. 3 Enter Yes in the Display Advanced options. perform the following tasks: a Right-click an attachment field corresponding to the contents of the attachment. then an error is generated and is viewable in the Error tab. 4 Click the Advanced Options tab. 2 Fill in header information. 6 In the attachment pool. Message Information tab The Message Information tab records status information about the email. as shown in Figure 3-26. The system needs to be able to read and parse the contents of these attachments when it creates the outgoing email. and if there is any delay in sending the message. c Select a file. You can attach only one of each type of alternative attachment to a message form. 5 Click the Attachment Alternatives tab. 7 Select an encoding for the attachment or leave the field empty to use the system default. the dates sent and received. Chapter 3 Outgoing email 87 . b Select Add to open the Add Attachment dialog box.Using the Email Messages form to send outgoing email To add an attachment alternative 1 Create an outgoing message. These attachments are stored as part of the message in the message form. Errors tab The Errors tab enables users to view error messages if an email is not sent correctly. such as the Message ID. 8 Send the outgoing email. if the To field has an invalid character like a space. NOTE In terms of performance. Step 3 If none of the items in the previous steps is supplied. If none of these points is true. If you do not supply field values. or both) to the Content attachment fields in the Attachment Alternatives tab of the AR System Email Messages form.04 Determining message content of outgoing email When sending an email message. the message creation will fail. 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. or both). For query information to be used. the information will be used to determine values for variables contained in the template. but your content template contains a query to obtain information to substitute in the email. 88 BMC Remedy Email Engine Guide . server. Step 2 If you do not supply a template.BMC Remedy Action Request System 7. the attachment will be used to determine the values for variables contained in the template. 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. a form. the system uses it as the message body. the message content is determined according to the following sequence: Step 1 If you supply a template. Character sets in outgoing mail The JavaToMimeMapping. and qualification must be supplied. the query information will be used to generate the message. You can find this file in the Email Engine installation directory. the system uses the template as is. a query against another server is more expensive than a query against the current server. If you do not supply an attachment in the Values attachment field.properties file contains a list of character set conversions for your outgoing mail. If any one of these items is missing. but attach a file (HTML or plain text. set up an email system on another server.6. the system uses these attachments as the content. 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. If you are going to send many emails based on information queried from another server. 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. Sending reply email: Giving a professional look to outgoing email 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. Chapter 3 Outgoing email 89 BMC Remedy Action Request System 7.6.04 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 BMC Remedy Email Engine Guide Sending reply email: Giving a professional look to outgoing email 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. Chapter 3 Outgoing email 91 BMC Remedy Action Request System 7.6.04 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. 92 BMC Remedy Email Engine Guide Sending reply email: Giving a professional look to outgoing email 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. Chapter 3 Outgoing email 93 5 Create a new email in your email client and address the email to the Email Engine inbox account.eng. 4 Export an email template from the HD Incident form. and then fill out the required information for the template.6. see “Exporting mail templates” on page 144. see “Adding attachments to HTML templates” on page 162. and then make sure you filled in all the required fields. 2 Create a result template for your reply email. 7 Add the result template parameter to the email. 6 Copy and paste the contents of the exported email template into the new email.com Login: Demo Password: Action: Submit Result: Results Template Default # Values: Submit. not the field ID. For more information. For more information.BMC Remedy Action Request System 7. The variables for field values must use the field name (its database name) as the variable name.04 To use HTML result templates with outgoing email 1 Make sure the Email Engine is properly configured to send reply results. see “Configuring the Email Engine for replying with results” on page 41.bmc. For more information. The fields that are referenced in the result correspond to fields used in the HD Incident form. Figure 3-31: An HTML result template 3 Create an entry in the AR System Email Templates form for your result template. Figure 3-31 is an HTML result template designed for this exercise. Your email should look like the following example: # # File exported Tue Sep 28 17:01:33 2004 # Schema: HD Incident Server: POLYCARP. Query 94 BMC Remedy Email Engine Guide . Status ! 7!: New # Values: New. you should receive a reply email (as shown in Figure 3-32) that includes the results of your submission. High. Chapter 3 Outgoing email 95 . Resolved. Assigned. If you properly configured the Email Engine and included all the required fields and the result template in your email. Closed Submitter ! 2!: $USER$ Impact !536870927!: Low # Values: Low. Full Last Name+ !536870916!: Stamps First Name !536870917!: Ivan Location !536870918!: Sunnyvale Email Address !536870920!:
[email protected] reply email: Giving a professional look to outgoing email Format: Short # Values: Short. WIP. see “Creating an email reply using result templates in HTML format” on page 227. Medium.bmc.com Phone !536870919!: 408-555-1212 Category !536870913!: Networking Type !536870914!: VPN Item !536870915!: Cisco Problem Summary ! 8!: Need to install VPN Client. Figure 3-32: A reply with results email For more information. Urgent 8 Send the email to the incoming mailbox. The following example uses XML format when creating a result template. The name of this XML template is employee. Figure 3-33 on page 97 displays the outgoing email generated by the Email Engine.xml) using XML format: <?xml version="1. 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. 2 Add the template as a text template to the AR System Email Template form.BMC Remedy Action Request System 7. an attribute value (#$$Employee Name$$#). see “Storing templates in the AR System Email Templates form” on page 161. TIP You can easily validate your XML file by displaying it in a browser. 96 BMC Remedy Email Engine Guide . For information. The results from a query are returned in XML. To use XML with outgoing email 1 Create a template file (for example. and several elements (age) with their values (#$$Age$$#). 3 Send an incoming email to the Email Engine that queries the server and returns the results using the XML template.6. result_employee.04 Using XML result templates with outgoing email You can use XML when creating templates for outgoing email.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). if you need to send a questionnaire seeking input from users. you can create HTML templates to include content similar to header templates. the resulting email (combining an HTML header template with an XML result template) would no longer be displayed in purely XML format. instead of as plain text. but the Email Engine does not support linking your HTML template to a cascading style sheet. and so on. If your outgoing mailbox is configured to include an HTML header. you can include HTML fields in the email message so that users can enter input using text boxes.Sending reply email: Giving a professional look to outgoing email 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. Using HTML content templates with outgoing email Rather than entering raw HTML into your outgoing email. You can include embedded styles in your content file. To add content to an outgoing email message 1 Create an HTML template that you will include in your outgoing message.2 Final//EN"> <HTML> <HEAD> <TITLE>BMC Picnic</TITLE> </HEAD> Chapter 3 Outgoing email 97 . For information about encoding user-defined markup text in outgoing email messages. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3. radio buttons. The following sample HTML template defines font styles and colors in the <BODY> tag. see “User-defined HTML or XML text in outgoing HTML emails” on page 102. For example. <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. 5 (Optional) Include a header or footer template. <input type=radio name="F7">Yes</radio> <input type=radio name="F7">No</radio></font></i><br/> <i><font color=#777777 face="Arial. for example. specify BMC_Picnic_Invite. 4 Under the Advanced Configuration tab. BMC_Picnic_Invite.04 <BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#FF0000" VLINK="#800000" ALINK="#FF00FF" BACKGROUND="?"> <i><font color=”blue” face="Arial.BMC Remedy Action Request System 7.6. Helvetica">Number of additional guests . see “Adding attachments to HTML templates” on page 162. 3 Open the outgoing mailbox entry in the AR System Email Mailbox Configuration form. your email will use any default templates configured for your outgoing mailbox. Figure 3-34: An outgoing message with the header and HTML content templates 98 BMC Remedy Email Engine Guide . Otherwise. Figure 3-34 displays the outgoing email sent by the Email Engine to your mail client. Helvetica"><h3>Are you coming to the BMC company picnic? . For more information. 6 Send a sample outgoing email.html. Helvetica"> <h1>BMC Company Picnic</h1></font></i><hr> <i><font color=#777777 face="Arial.html as the content template. AppendedText$$#</td> Chapter 3 Outgoing email 99 . contact your <a href="mail%20to:%
[email protected]. containing only basic information.Sending reply email: Giving a professional look to outgoing email Using status templates with outgoing email When an error occurs while executing instructions from an incoming email.com">Administrator</a>.Type$$#</td> <td width="18%">Message 2</td> <td width="42%">#$$ActionStatus. error messages. as shown in Figure 3-35. for example. The following procedure shows you how to create an HTML template that formats status more attractively.</b></ div> </td> </tr> <tr> <td width="12%">Error Number</td> <td width="28%">#$$ActionStatus. To include status templates with outgoing email 1 Create a status template. 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. This system-generated email is simple. your outgoing email can look more professional as well. the Email Engine automatically generates an outgoing email with relevant status information. Appended Text: TestSecurityForm By using an HTML status template.Text$$#</td> </tr> <tr> <td width="12%">Error Type</td> <td width="28%">#$$ActionStatus. The following sample HTML template is created to display status: <html> <head> <title>Status Template</title> <meta http-equiv="Content-Type" content="text/html. If you have questions.Number$$#</td> <td width="18%">Message 1</td> <td width="42%">#$$ActionStatus. the type of instruction that failed. 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. 5 (Optional) Include a header or footer template. and so on. It also includes an email address that users can respond to if they have questions. 6 Send an incoming email to the Email Engine that will generate an outgoing status email. Of course. your HTML template could include color. a query that returns no records.html as the status template. Status_default. Figure 3-35: An outgoing message with the default header and HTML status templates 100 BMC Remedy Email Engine Guide . for example. see “Adding attachments to HTML templates” on page 162. 3 Open the outgoing mailbox entry in the AR System Email Mailbox Configuration form. 2 Create an entry in the AR System Email Templates form for your status template.6.BMC Remedy Action Request System 7. 4 Under the Advanced Configuration tab. Figure 3-35 displays the outgoing status email generated by the Email Engine. For more information.html. specify Status_default. for example. special fonts. The sample email shown in Figure 3-35 uses the default header template configured for the outgoing mailbox.04 </tr> </table> </body> </html> This HTML template defines a simple table with two rows for the error number and error types. Sending reply email: Giving a professional look to outgoing email Including incoming body in outgoing email By default.bmc. 2 Associate the status template with your system’s outgoing email messages. Email Engine generates an error message based on MyStatusTemplate. To include the incoming body in outgoing email 1 Add the variable #$$ORIGINALMAIL$$# to a status template. See “Using status templates with outgoing email” on page 99. 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. and query actions. StatusTemplate: MyStatusTemplate The status template associated with the user’s request.com Login: Demo Password: Action: Submit Description !8!: My mouse isn’t working. MyStatusTemplate.Text$$# Appended Text: #$$ActionStatus. Because the value of the Original Mail label in that template is the variable #$$ORIGINALMAIL$$#.eng.Type$$# Text: #$$ActionStatus.AppendedText$$# Original Mail: #$$ORIGINALMAIL$$# If the user’s submission fails.Number$$# Type: #$$ActionStatus. 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. When Email Engine generates an error message based on a status template containing the variable #$$ORIGINALMAIL$$#.eng. For example. use the variable #$$ORIGINALMAIL$$# to include the incoming body in outgoing messages. a user submits an email request that includes this information: Schema: HD Incident Server: reepicheep. includes these label/value pairs: Error Error Error Error Number: #$$ActionStatus.bmc. it replaces the variable with the body of the original email message. modify.com Login: Demo Password: Chapter 3 Outgoing email 101 . [#ENCODE_HTML_END#] IMPORTANT You can only specify these markers directly in the HTML Body tab. and schema (form name) values IDs of the attachment fields Names of the attached files For example. Email Engine gets the appropriate HD Incident form from the specified server and then gets the attachment information from the specified attachment fields..txt !536880913!: file2. or both. and the incoming request must contain the following information: Correct login.com Login: Demo Password: Action: Submit Description !8!: I need a new mouse for my computer. 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#] . server.txt Using that information.. Email Engine cannot get file2.txt. password. the user receives an error message that includes the original email message and only one attachment. StatusTemplate: MyStatusTemplate Including incoming attachments in outgoing email To include attachments to incoming requests in outgoing error messages.eng. or in an HTML content template. file1.04 Action: Submit Description !8!: My mouse isn’t working.txt.BMC Remedy Action Request System 7.bmc. 102 BMC Remedy Email Engine Guide . the associated status template must contain the variable #$$ORIGINALMAIL$$#. a user submits an email request that includes this information: Schema: HD Incident Server: reepicheep.6. StatusTemplate: MyStatusTemplate !536880912!: file1. Thus. if the submission fails. If the HD Incident form does not contain field 536880913. which should not be rendered as HTML content: <Timespan=“app. the email client correctly renders the user-defined markup as follows: Leave application Approved <Timespan=“app. The output appears as follows: Leave application Approved You need to indicate that the following text is user-defined markup. consider that you enter the following markup in the message body: <html> <body>Leave application <br> Approved <br> <Timespan=“app. For example. the recipient client does not render the text as HTML. it displays the text as is.User-defined HTML or XML text in outgoing HTML emails If you include user-defined markup text in outgoing HTML messages.calendar” string=$today$/> To indicate user-defined markup.calendar” string=$today$/> [#ENCODE_HTML_END#] </body> </html> When the message is received. Instead. construct the message body as follows: <html> <body>Leave application <br> Approved <br> [#ENCODE_HTML_START#] <Timespan=“app.calendar” string=$today$/> Chapter 3 Outgoing email 103 .calendar” string=$today$/> </body> </html> When the message is received. the email client attempts to render the text as HTML. 6.BMC Remedy Action Request System 7.04 104 BMC Remedy Email Engine Guide . Chapter 4 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 . To make email easier to use. Incoming Mailbox Email Engine 3 Email engine parses instructions. for example.04 How incoming email works Figure 4-1 presents a sample scenario that demonstrates how the Email Engine receives incoming email. 106 BMC Remedy Email Engine Guide . 4 Server creates ticket. Instructions then translated into API calls to server. Figure 4-1: How the Email Engine receives incoming email Underlying Database AR System Server HD Incident Email Engine Printer Broken 1 AR System admin configured incoming mailbox in email engine. submitting entries to the HD Incident form. he has created and sent to his user base several email templates that cover typical work situations.6. 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.BMC Remedy Action Request System 7. and querying the status of their tickets. Email account Mail Server "Printer broken!" 2 Submit email sent to incoming mailbox. 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 BMC Remedy Action Request System 7.6.04 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 filter’s Run If condition, the filter will fire, regardless of whether the client is BMC Remedy User or an email. Sending a query instruction to the Email Engine The easiest way to send queries to the Email Engine is to think of email as simply another client of 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 BMC Remedy Email Engine Guide Sending a query instruction to the Email Engine 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 BMC Remedy Action Request System 7.6.04 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 BMC Remedy Email Engine Guide Sending a query instruction to the Email Engine 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 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. the email returned from the Email Engine will indicate this. it will be automatically assigned a value of Full. 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. which will return all fields in the form.6. 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. To use the Format label 1 Create an email. by default.BMC Remedy Action Request System 7.04 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. just like the results you would see in BMC Remedy User. 112 BMC Remedy Email Engine Guide . Sending a submit instruction to the Email Engine Sending a submit instruction to the Email Engine Like BMC Remedy User. 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. for example. you can use email as a client of AR System to submit entries on the server. 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. The Email Engine will parse only the characters between the exclamation marks. 2 Address the email message to the incoming mailbox. To execute submit instructions to the Email Engine. As with a Query action. send an email with instructions with the Action label set to Submit. To submit an entry into a AR System form. 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. 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 . Submit actions can also use the field ID instead of the database field name. 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. $$] The Email Engine will correctly parse the syntax when the email is submitted. 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. for example.BMC Remedy Action Request System 7. if you have a longer value for the Short Description. then enclose it between [$$ and $$]. Make sure your incoming email includes all required fields. If you successfully submitted your email. Figure 4-5: An error message reply from the Email Engine 114 BMC Remedy Email Engine Guide . Submitter. the Email Engine will return an error message (as shown in Figure 4-5) that indicates missing parameters. (For more information about this configuration option. see “Advanced incoming mailbox configuration” on page 33.04 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.6. so use this syntax. then all the fields of the newly created entry will be returned to the sender. it could be sent to the Email Engine as: ! Short Description!: [$$This is a longer description which spans multiple lines. For example. 4 Send your email.) If the entry cannot be created. 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. Instead of specifying a text value. 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. the Format label is set to Full. By default. see “Incoming and outgoing mail templates” on page 141. you can use keywords. 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. which means all fields in the form are included in the confirmation email. If Reply With Entry is set to No. like the status template shown in Figure 4-5.Sending a submit instruction to the Email Engine TIP Another benefit of the Email Engine is that status from the Email Engine can be formatted. configure the incoming mailbox Reply With Entry parameter to Yes. To use the Format label. then the Format label is ignored and the confirmation email will contain only the Request ID number. Using keywords You can use keywords such as $USER$ to supply the actual value for the field. Chapter 4 Incoming email 115 . 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. For more information. To include only fields from the results list in the confirmation message. 3 To include an attachment in an email.log files to insert into the 536880912 attachment field.log The Email Engine will accept the email submit instruction. the file name remains intact. If the attachment name including the extension is not supplied. 116 BMC Remedy Email Engine Guide .msg extension. make sure the mail client you use is sending the file name of the attached message properly. send an incoming mail with a message attachment. Do not include two attachment files with the same name. Attachment field !536880912!: filter. but to specific attachment fields. however. then view the Attachment tab on the Email Messages Form for the name of the attached file.BMC Remedy Action Request System 7. To include attachments 1 Create a new email message in your mail tool. NOTE If you are using message/rfc822 attachments with a submit template. 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. If you use Outlook Express to submit the message to the Email Engine and save the attachment by using the . the Email Engine cannot recognize which of the two filter.04 Including attachments with incoming email Submit instructions can also include attachments. 2 Address the email message to the incoming mailbox.log Your label/value pair syntax should not see the attachment pool. the email submission will not pass the attachment to the attachment field.log Attachment field 2 !536880913!: filter. as in the following example: Attachment field 1 !536880912!: filter. 4 Insert your attachment file anywhere in the email.log file.6. To test this. Email engine parses 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. Chapter 4 Incoming email 117 . 2 Francie Frontline sends email with 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 3 Joe User replies to email. Key: 1234 Action: Modify Underlying Database HD Incident Outgoing Field 1 Field 2 Field 3 Email Engine Jklm Nop Qrst Abcd ef ghijkl mno Email Messenger Form AR System Server 5 Server modifies ticket.Sending a Modify instruction to the Email Engine 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. you must configure the Email Engine to accept modification requests. To allow users to modify an entry. Do not delete outgoing email notifications with modify instructions. Figure 4-6: Using incoming email to modify requests 1 AR System admin configured email engine to allow modify entries. He updates the work log label/value pair in the email. If the email had failed (for example. Francie Frontline. Step 5 The Email Engine returns the results to the sender. Step 2 Joe User has a serious problem with his PC. NOTE The incoming and outgoing mailboxes in the Email Engine can be one physical mailbox. he knows how to include additional fields to update information about the new department he was transferred to. who has AR System administrator privileges. the Email Engine returns an error message that indicates faulty parameters or other problems. Joe modified the encryption value or he tried to use a different Request ID). He needs an IT engineer to install the latest service patch and has submitted an entry on the HD Incident form (Request ID 000000000000055). performing both the incoming and outgoing functions.BMC Remedy Action Request System 7. After she sends her email. see the following procedures. !Department!: Product Marketing. Worklog !536870922!: I’m running Service Patch 6. Joe User. for example. She needs Joe to verify his current PC configuration and modify his ticket with updated information. see “Configuring the Email Engine for modify actions” on page 42.04 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. is working on Joe’s ticket. Step 4 The Email Engine receives the reply from the mail server and verifies that Francie’s original email exists in the Email Engine (in the AR System Email Messages form) and that the sender’s email address is contained in the recipient field of the original email. For more information. for example. for example. Step 3 Joe User replies to the email. She also includes names of fields that Joe can modify. For more information.6. 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. and modifies the ticket in the HD Incident form. 118 BMC Remedy Email Engine Guide . It then parses the modify instruction in Joe’s email. Because he has used email to submit and query AR System entries. a copy of the email is stored in the Messages form and the email is sent to Joe. the IT department. c In the Reply To field. The message can be sent in plain text or HTML format. see page 122. b In the To field. you can provide field IDs or database names of fields that have values that can be modified. 2 Open the AR System Email Messages form in New mode. which the administrator can be supply in the outgoing message or the user can supply in the reply The Action Label. and enter the following information: a In the Mailbox Name field. which describes the type of action or instruction to be executed (In this example. an organization. the Action Label is set to Modify. select an outgoing mailbox. enter the name of the user you are sending the email to. (To use HTML. enter the email address of the incoming mailbox that has been configured to accept modify instructions. d Enter other information as needed.) Step 2 The user replies to the message with new values of the entry the user wants to modify (see page 121). 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 . Sending modify instructions To send modify instructions to a user 1 Log in to BMC Remedy User as a AR System administrator user.) Form or Schema name on which to execute the instruction Request ID of the entry the user can modify Optionally. for example.Sending a Modify instruction to the Email Engine 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. 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. Figure 4-7: A sample outgoing message sent by the administrator to a user You can substitute field IDs for database names. 4 Click Send to send the mail from the outgoing mailbox to the user.04 Schema: HD Incident Request ID: 000000000000003 !536870913!: This message allows Joe User to modify Request ID 000000000000003 of the HD Incident form. For example. 120 BMC Remedy Email Engine Guide . you can enter comments before the field ID.BMC Remedy Action Request System 7. the Email Engine appends an internal label called ##Modify##. if the Problem Summary field is field ID 8. When you send the email. Figure 4-7 shows an outgoing message you might send to a user. The Problem Summary field has been specified in the outgoing message. then you could replace the database name with its field identifier !8! and produce the same results: !8!: Optionally. Schema Name. The Email Engine generates an encrypted value for this label by using the Server Name. and Request ID (as shown in Figure 4-8 on page 121).6. Joe User can also modify additional fields in his email reply by adding more field IDs. you can use a result template as its equivalent when performing a Modify action with incoming mail. for example: Enter problem summary!8!: NOTE Because there are no content template labels. (For information about creating security keys. 3 In the reply.Sending a Modify instruction to the Email Engine Replying to email containing modify instructions To reply to an email containing modify instructions 1 Open your email client. For example. 4 Fill in any missing parameters as needed—Login. Schema name. NOTE You must reply to the same mailbox as the one from which the email was sent. or Server label/value pairs when replying to the administrator’s email. modify parameters as needed. query or modify instructions to the email. Password (if there is a password). you could assign values for !8!. WARNING The user who is replying cannot add additional submit. and Key.) Chapter 4 Incoming email 121 . see “Testing your mailbox configuration” on page 36. Joe User received an email that looks like Figure 4-8. the Problem Summary field. Do not change the Request ID. Figure 4-8: The Modify instruction sent to a user 2 Open a reply window for the email that contains the modify instructions. 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 . When the incoming mailbox of the Email Engine receives the reply from the user. see “Sending modify instructions in plain text” on page 119. create an outgoing message in New mode. it makes sure that the original email sent by the administrator exists within the Email Engine and that the sender’s email address is contained in the recipient field of the original outgoing email. the Email Engine returns the results to the email client. Sending modify instructions in HTML In addition to the plain text format.6. using the HTML format can help prevent user errors. the Email Engine returns an error message that indicates any missing parameters or other problems.BMC Remedy Action Request System 7.04 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. you are forcing users to respond to the modify instructions exclusively with the HTML controls you have defined. As a result. If you successfully modified the entry. 5 Send the email reply. Otherwise. Joe User also modified the contents of the Short Description field (field ID 8). To send modify instructions using HTML 1 Using the AR System Email Messages form. 2 Click the HTML Body tab. For sample contents of an outgoing message. By sending modify instructions in HTML. Using HTML form controls gives administrators greater control over the content that users can modify. The Email Engine then parses the email. you can send modify messages from the AR System Email Messages form in HTML format. Modify the contents of the Assigned To and Short Description fields. When users enter their password. Modify the status in an input type Radio control field. The user receives an email that looks like Figure 4-9 on page 124. Chapter 4 Incoming email 123 . server name or form name) in hidden fields. Users can select only one radio button option.Sending a Modify instruction to the Email Engine 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.org/). With HTML format. 4 Send the outgoing email. stars appear instead of the typed symbols or letters. you can also include system information (for example.w3. 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. but users do not see it. The data is still within the message. enter Assigning this ticket to Bob Backline in the Short Description field. Also observe that Joe’s password is encrypted (Figure 4-10). reply to the email received with the modified values for the HTML fields that you can see and have permission to change.6.BMC Remedy Action Request System 7.04 Figure 4-9: A Modify instruction (HTML format) sent to the user 5 To execute the modification. click in a field to modify its contents. Figure 4-10: Responding to the Modify instruction (HTML format) sent to a user Using the HTML controls you have defined. for example. 124 BMC Remedy Email Engine Guide . you can include multiple modify instructions in one email message if you include the full login information (server. creating outgoing HTML email requires some planning by administrators. login. Like logging in to BMC Remedy User. the Email Engine would reject the modify action due to permission problems. Chapter 4 Incoming email 125 . provided multiple instructions (modify with submit or query) have been sent from the administrator. he could not use email to “log in” to the Email Engine without entering a password. if Joe User could not enter his password. Email is no different than any other AR System client. Additional restrictions Remember the following restrictions when using email to modify entries: The Email Engine does not support the Modify All operation. and password) for each entry that you want to modify. For example. As a result. 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. Users cannot add new instructions when replying to the message containing modify instructions.Sending a Modify instruction to the Email Engine With HTML. users can modify only the fields you provide. Only one entry can be modified with one modify instruction. However. 04 Using workflow to modify requests Figure 4-11 presents a sample scenario that demonstrates how to use workflow to modify requests. Email Engine 2 AR System receives submit request. 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. Created security key.6. see “Configuring the Email Engine for modify actions” on page 42. 126 BMC Remedy Email Engine Guide . Figure 4-11: Using workflow to modify requests AR System Server 4 AR System verifies security mechanisms and modifies the request. Incoming Mailbox Outgoing Mailbox Mail Server 3 User receives email. Email sent includes Modify template. For more information. and created and sent security keys to trusted users of AR System. NOTE The incoming and outgoing mailboxes in the Email Engine can be one physical mailbox. enabled the incoming mailbox to accept modify instructions. He has associated the incoming and outgoing mailboxes. Filter workflow triggers Notify action. 1 AR System admin configured incoming mailbox to accept modify actions. performing both the incoming and outgoing functions.BMC Remedy Action Request System 7. make sure that the Demo user is still active and has an email address that works with the Email Engine. For example. Creating a security key Use the following values to create a AR System Email Security record. for example. and the request ID. Make sure your incoming and outgoing mailboxes work correctly. 7 Set the Expires field to No. To create a security key 1 In BMC Remedy User. Step 3 The user receives the message in her email client and then replies to it. 5 Set the Force For Mailbox field to No.Creating workflow to modify requests Step 2 AR System receives a submit request. set the polling intervals on your incoming and outgoing mailboxes to one minute so that you can quickly verify your results. Chapter 4 Incoming email 127 . A filter uses email to send a notification that a request has been received. 3 In the Key field. 8 Leave the rest of the fields blank and save the record. 6 Set the Force From Email Addresses to No. The example is simple but complete. Creating workflow to modify requests The following example walks you through the procedure for creating workflow to modify requests. open the AR System Email Security form in New mode. and you can easily add more functionality. This email is formatted by using a modify template. in this example. define your security key. 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. In this example. the user’s email address. 4 Enter Demo as the User Name. Finally. patience. 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. 2 Set the Status field to Enabled. Demo. Step 4 The AR System server verifies the security key. 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. You must provide a security key for every user who sends modify instructions to the Email Engine. 10 In the Subject field.6. To create a sample form 1 Create a new form and name it appropriately. you can add a Run If qualification later. For more information. enter Modify Email Workflow. 5 Leave the Run If condition blank. select Notify. 7 From the New Action list. 4 Select Submit as the Execute On condition. 8 In the User Name field. for example. 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. select Email. 2 Enter a filter name. Modify Email Workflow. After you verify that you can use your filter workflow to modify requests. 6 Click the If Action tab. 128 BMC Remedy Email Engine Guide . Modify Email Filter. see “Modify action” on page 149. 2 Do not add any new fields. 3 Save the form. To create filter workflow 1 Create a filter. 9 From the Mechanism list. The Modify action is valid only in Reply with Result emails.04 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.BMC Remedy Action Request System 7. 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. 3 Select Modify Email Workflow as the Form Name. enter Demo. 12 Save your filter. 11 In the Text field. for example. Creating workflow to modify requests Exporting an email template Export an email template from the Modify Email Workflow form. for example: # # File exported Tue Sep 21 15:34:56 2004 # Schema: Modify Email Workflow Server: POLYCARP. 4 In the Form Selector dialog. select the views your want to use in the template. Full Submitter !2!: Demo Short Description !8!: Email Test 5 Send the email to the incoming mailbox..] button next to the To File field to specify the file name and location where you want the templates stored.bmc. 5 In the Export Mail Template dialog. 3 Enter a subject line. b Click the ellipsis [.. and click OK.. and then enter the required information for the template. 3 In the Export Mail Template dialog.] button next to the Form field. To create a test email 1 Create a new email in your email client. c Click Finish. select Modify Email Workflow form. right-click serverName. 2 In the AR System Navigator. for example. and choose Export > Mail Template.com Login: Demo Password: Action: Submit # Values: Submit. click the ellipsis [. perform the following actions: a In the View Details table. 6 Open the email template in a text editor.. Modify Email Workflow. 2 Address the email to the Email Engine inbox account.eng. To export email templates 1 Log in BMC Remedy Developer Studio as a AR System administrator. For more information. You use this email to submit a record to the Modify Email Workflow form. Creating a submit email Here you open a new email message and paste the contents of the exported mail template into the new email. 4 Copy and paste the contents of the exported email template into the new email. Chapter 4 Incoming email 129 . see “Exporting mail templates” on page 144. Query Format: Short # Values: Short. 04 Replying to email notifications The email client sends your submit email to the incoming mailbox on the mail server. The following procedure describes how you reply to email notifications generated by workflow. 2 Confirm that the incoming mailbox has received your message. The server then creates a record in the Modify Email Workflow form. 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. open the Modify Email Workflow form in Search mode.6. Figure 4-12: Incoming and outgoing messages in the Email Messages form 3 In BMC Remedy User. After receiving the email from the mail server.BMC Remedy Action Request System 7. 130 BMC Remedy Email Engine Guide . The incoming mailbox is configured to reply with results and generates an email response. when a record is submitted. Also. and makes the submit API calls to the AR System server. 5 Check for new mail in your mail client. and then sent the Reply with Result email (as shown in Figure 4-12). 4 Make sure a new record was created in the Modify Email Workflow form. To reply to email notifications 1 Open the AR System Email Messages form in Search mode. the Email Engine parses the instructions in your email. filter workflow triggers a Notify action that includes instructions for modifying the record. Creating workflow to modify requests 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. Update the Short Description so that you can verify that modifications work on records in the Modify Email Workflow form. 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. Chapter 4 Incoming email 131 . 8 Send the reply email. Do not edit this key in any way! 6 Reply to the returned email. 2 Set Enable Modify Actions to Yes in the AR System Email Mailbox Configuration form for the incoming mailbox. Figure 4-14: A Modify message returned to the incoming mailbox 10 In BMC Remedy User. TestModify) that includes a modify action. for example. 132 BMC Remedy Email Engine Guide . The procedure assumes you have created a form named TestSecurityForm. refresh the query results of the Modify Email Workflow form. confirm that the incoming mailbox has received the email with the modify instruction (as shown in Figure 4-14). 3 Make sure you have a valid security key. which contains at least the core fields. 4 Create a template (for example. the use of templates. 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.BMC Remedy Action Request System 7. 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.04 9 In the AR System Email Messages form. sending query and modify instructions to the Email Engine.6. and so on. Form. Include a Query action in the body of your email. you can construct an email that gives you the flexibility to search for a specific parameter.Searching for an entry to modify: Advanced solution You will use this template for the reply email. you could have omitted the Qualification line from the email. The Email Engine generates a reply (Figure 4-15) to the Query action. 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. 6 Use your mail client to create an incoming mail. 5 Add the TestModify template to the AR System Email Templates form. and then to perform the modify action in the TestModify template. The Email Engine also creates a Modify Key based on the information in the Action. by using the variable in the template. TIP If the Qualification was part of the TestModify template. 7 Send your email to the incoming mailbox. You can see that the Request ID value found from the query was substituted in the reply. Chapter 4 Incoming email 133 . see the Result Template label in step 6. and Request ID and adds it to the email. 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$$#$$]). by using the template you created in step 4 and specified as the Result Template. add values in !2! (a different name) and !8! (modifying the short description). and Key.BMC Remedy Action Request System 7. 9 Fill in any essential missing parameters—Login. Do not change the Action. Figure 4-16: A confirmation email that the modify action was successful 134 BMC Remedy Email Engine Guide . 10 Send the email reply with the modifications included. For example. and Request ID label/value pairs. Password (if there is a password).6.04 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. Form. you can use variables in templates. The Email Engine then sends you a confirmation message. 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 . The Email Engine parses the email and the server modifies the entry. You can perform a search on the form to verify the result. then enclose the variable with brackets: [$$ … $$] The following example of a template file (. as shown in Figure 4-16. Because the variable might span multiple lines. Use the following syntax for variables: #$$Variable Name$$# If you expect the value of a variable to span multiple lines. When you send a submit instruction. Variables are useful when you need to substitute values for the fields to submit an entry. The variable is called VEmployee_Name. it is enclosed by brackets [$$…$$].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.Using variables with templates NOTE You must reply to the same mailbox as the one from which the email was sent. Using variables with templates With incoming email. you also can provide a value for variable $$VEmployee_Name$$. BMC Remedy Action Request System 7. 136 BMC Remedy Email Engine Guide . you typically will not see information under the Templates and Variable Replacement tabs. Message Information. and email client formats. The tab displays the links to each message as it is rendered by the Email Engine in plain text. 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.04 Displaying advanced options for incoming email For incoming email. 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. or Errors. 4 Select one of the advanced option tabs: Advanced Options.6. NOTE For incoming email. 2 Select an incoming email message. 3 Select Yes in the Display Advanced Options field of the AR System Email Message form. HTML. as shown in Figure 4-18. along with an error message that indicates the reason for the failure. the original message is returned. the date the email was received. Figure 4-19: Error information for incoming email Chapter 4 Incoming email 137 . and how the message was parsed. such as its Message ID. 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.Displaying advanced options for incoming email Message Information tab The Message Information tab records status information about incoming email. error number.6.properties file contains a list of character set conversions for your outgoing mail. Information includes the severity of the error.04 Figure 4-19 illustrates an incoming query that did not return any results. Character sets in incoming mail The MimeToJavaMapping. You can find this file in the Email Engine installation directory. 138 BMC Remedy Email Engine Guide . date created.BMC Remedy Action Request System 7. and error message text. 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 .Chapter 5 Using email templates This chapter provides information and instructions for creating and using templates for outgoing and incoming email. their use in incoming and outgoing mailboxes. or complete any other such action. or XML. Labels are keywords unique in the Email Engine. 140 BMC Remedy Email Engine Guide . submit or modify an entry. as well as label/value pairs. For outgoing messages (sent by the Email Engine by using an outgoing mailbox). usually referred to as label/value pairs.04 Overview of Email Engine templates This chapter describes the various types of templates. and content of your email messages. Label/value pairs can be included in templates and used to instruct the Email Engine to interact with your AR System server.6. and values are their data. footers. The Email Engine parses (that is. translates) these instructions into commands to the AR System server to perform a query. HTML. 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. Templates used for incoming and outgoing messages can be formatted by using plain text. users can include templates in their emails that contain specially formatted instructions. A variety of email templates also function as the actual headers.BMC Remedy Action Request System 7. These instructions use combinations of field labels and their values. templates can provide formatting of content in messages that include the results of queries or various other requests. Email templates serve two main functions for incoming and outgoing messages: For incoming messages (email that users send to an incoming mailbox). 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 content template is attached by using the AR System Email Messages form or by using workflow with filters and escalations. or export them by using BMC Remedy Developer Studio. This section presents an overview of the different types of templates. footer. Header and footer templates—Used to place lines of text or a graphic at the beginning or end of a message. You can create these templates in a text editor (shown in the following figure). The content template can also contain formatting instructions and label/value pairs to specify a header. selecting the form and fields that are to be contained in the template. make sure that you include the fields specified in the content template in the Fields tab of the Notify action. which are all described in more detail later in this chapter. Content templates can also be formatted in HTML. similar to the result template shown in Figure 5-3 on page 142. They can also contain plain text or reserved variables. If they are specified in content templates or an email body as label/value pairs. Content templates—Used for outgoing messages. Chapter 5 Using email templates 141 . or status template. Incoming and outgoing mail templates You can create separate templates to specify different formats for incoming and outgoing mail. result.Types of templates Types of templates You can create specific templates for various functions. Figure 5-1: A plain text content template When using a content template with workflow. they will be applied to the email reply. They can be specified in the outgoing email using the AR System Email Messages form. These templates can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. BMC Remedy Action Request System 7.6.04 Figure 5-2: An HTML header and footer template Result templates—Defines the format to use when replying to an incoming instruction with the results of an action. A label/value pair must be specified in the email containing the action. Result templates can be either HTML or plain text. Figure 5-3: Result template—HTML Status templates—Used 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 BMC Remedy Email Engine Guide 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. Chapter 5 Using email templates 143 BMC Remedy Action Request System 7.6.04 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 BMC Remedy Email Engine Guide 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: Overwrite—Overwrites the mail template of an existing file. This option is useful when you are re-exporting a template that has changed. Append—Appends the contents to an existing file. If several templates are in a single file, the mail processor will not be able to process the request. The template is saved as a 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. Chapter 5 Using email templates 145 BMC Remedy Action Request System 7.6.04 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 BMC Remedy Email Engine Guide possible RPC.properties file” on page 180. Name. The Request ID of the entry on which the possible action must be executed. The Email Engine searches through the User form for the appropriate user name by searching for the email address.properties file. The alias for this label is Schema. If Key:securityKey matches an entry in the AR System Email Security form. the mail process verifies whether a default Workflow form was defined in the AR System Email Mailbox Configuration form. and TCP Port labels The Login and Password labels identify the user name and password used when executing the instruction. Use the supplied user information: user login name. then the corresponding user name is used.Using label/value pairs in templates 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. Server label The Server label identifies the server that the instruction will affect. The passwords and security keys are encrypted in the AR System Email Messages form. The aliases for Login are User. 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. Chapter 5 Using email templates 147 . (For more information. You must add Key:securityKey to the email. password. If no AR System form is specified or the specified form does not exist. 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. see “Updating the EmailDaemon. An example of a Server label/value pair is Server:serverName. possible authentication. the item is rejected because a form must be specified. and possible TCP inside the email by using the appropriate labels and values. the mail process defaults to the server information specified in the EmailDaemon. If not. An example of a Form label/value pair is Form:formName. The key associated with a given sender or user. and Login Name. Use the sender’s email address. User Name. It uses the first user it finds whose email address corresponds. possible language. Password.) Login. If no server is specified or the specified server does not exist. If no language is specified. use the format: Login <input type="text" name="!536870918" size=50/> With this format. the default values are used. or Password labels. for example.6. if your AR System server is not using the AR System portmapper. For example.04 NOTE If you try to send an email in an HTML template. Name. Language:en_US. the Email Engine can parse correctly that Login is a label for a field on the form and not an instruction. The values are the same as they are in the BMC Remedy Developer Studio and other AR System clients. do not use: Login: <input type="text" name="!536870918" size=50/> Instead. The alias for TCP Port is TCP. The alias for RPC Number is RPC.BMC Remedy Action Request System 7. 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. 148 BMC Remedy Email Engine Guide . The format of the Language label/value pair is Language:localeLanguage. The TCP Port label identifies the TCP/IP port of the AR System server. These values are the same as those used when logging in to the AR System server. Language label The Language label defines the locale used when logging in to the AR System server. do not use a colon in the Login. Chapter 5 Using email templates 149 . Modify. and a userdefined value. The syntax is Action:Submit. you can configure a limit to how many matches are returned in the message. Searches for entries on a specific AR System form. 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 email is only logged and no actual execution takes place.” page 102. The syntax is Action:adminDefinedText. The user must not modify the modify key included in the email. an additional message is provided that indicates what the limit is. Query action The Query action lets you search for existing entries. See the Configuration Guide. If a request exceeds the configured search match limit. An instruction that the administrator defines. The syntax is Action:Modify. 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. This is valid within any incoming email. Query. The syntax is Action:Query. User-Defined Submit action By using the Submit action in an email. An alias for Action is Instruction. If no value is given for the label. Modifies a specific entry contained within a specific AR System form. “Limit Number of Items Returned. You can see an example of a template with a Submit action in “Sending a submit instruction to the Email Engine” on page 113. see “Sending a query instruction to the Email Engine” on page 108. users can enter values for field labels. To increase server performance. 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. Valid actions are Submit.Using label/value pairs in templates Action label The Action label defines the operation to perform on a specific AR System form. This is only valid in reply emails (that is. The Action label/value pair is required in the incoming email so that the parser can generate valid instructions. For sample templates with Search (Query) actions. Valid values for this label are in Table 5-2. Modify action The Modify action enables you to modify existing entries. emails that have been sent to the user from a AR System server). and submit a new record. but due to the nature of this command and the security implications. 04 The sender or the user of the email must supply a valid Security Key.BMC Remedy Action Request System 7. with each entry separated by a line of hyphens. The Short format returns only the fields defined in the results list. For more information. see “Sending incoming email with user instructions” on page 167. For more information. the default format is Full. and Modify actions. 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. NOTE Do not modify the Password field (field ID 102). see “Using workflow to modify requests” on page 126 and “Sending a Modify instruction to the Email Engine” on page 117. For Query. see “Configuring the Email Engine for modify actions” on page 42. Submit. The Full format lists the information for all accessible fields. use only the Format label if the advanced configuration setting Reply with Entry is set to Yes for the incoming mailbox. 150 BMC Remedy Email Engine Guide .6. An example of a Format label/value pair is Format:Full. In Submit and Modify actions. If no fields are defined for the results list. A user-defined value can consist of any text. Format label For Query. as long as it is defined in the AR System Email User Instruction Templates form for user-defined instructions. In the outgoing mailbox. 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. 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. The incoming mailbox must be configured to allow modifications. All matching requests are listed in the body of the response. 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. you can specify that requested information be formatted in full or short form by entering Full or Short after this keyword. one after another. it returns the Short Description field. (For more information. The Result template is usually associated with a particular form. it retrieves the template file and uses it as required. see “Reserved variables” on page 159. The value can be any properly formatted search. Result Template label If the Email Engine is configured to send an email reply. The template consists of label/value pairs and variables that are replaced with relevant data. Status Template label The Status Template label is the name of the template to use when status information is returned. Aliases for this label are Query and Search. These variables are replaced by the data found on the form based on the instruction being executed. and specify the template name as the value. These variables correspond to the status information returned if any errors occurred while executing one of the instructions. such as 1 = 1. they make use of reserved words. For more instructions. An example of a result template label/value pair is Result:resultTemplateName. 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. This template consists of label/value pairs and variables (described on page 156) that correspond to fields on the AR System form being queried. 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. 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. you can specify a result template that formats the reply for you.) Chapter 5 Using email templates 151 . You include the Result Template label. When the Email Engine receives this label and value. 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 Result Template label defines the template to use when replying to an incoming email containing query instructions. For example. Aliases for this label are Result and ResultTemplate. All of the restrictions that apply to the Advanced Search bar in BMC Remedy User apply when performed through email.Using label/value pairs in templates Qualification label The Qualification label and its value are required only for a query-based instruction. aliases for the Footer Template are Footer and FooterTemplate. it retrieves the template and use it as required. An example of a status template label/value pair is StatusTemplate:statusTemplateName. The label/value pair method is used when requesting results from a server by way of email. For example. It is common practice to include the actual field name in this way: Submitter !2!: $USER$ 152 BMC Remedy Email Engine Guide . An example of a header template label/value pair is HeaderTemplate:headerTemplateName. an error will be generated. If this is a query action. !Name! or !ID! labels The !Name! and !ID! labels indicate a AR System field or the value of a variable. entries are clearly separated from each other. The Header and Footer templates typically contain basic text. Aliases for this label are Status and StatusTemplate. and decorative typefaces. 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. This text will not be parsed by the Email Engine. for example: !8! : Short description information Blanks are acceptable. it retrieves the template and uses it as required. or they can be HTML documents with logos.04 This template does not have to be related to a particular form. graphics. In this way. If any characters other than digits and spaces are between the exclamation points. after an Action: Query label/value pair—then the header or footer or both are inserted before or after (or both before and after) each entry that is retrieved when the action is executed. the reference is not recognized as a field ID. field ID 8 is !8!. If the templates are used within a Query action block—that is. 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). Labels for fields need not be present in any specific order within an email message. Aliases for the Header Template are Header and HeaderTemplate.BMC Remedy Action Request System 7. The value given for this label is the name or Request ID of a template contained on the AR System Email Template form. The exclamation marks are required to surround the field name or the ID number. A colon (:) is placed after the second exclamation point as a delimiter. 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. When the Email Engine receives this label/value pair. You can precede the field name/ID label with any text that you want to include.6. and the argument is of a different data type than defined for this field. For more information. 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. Fields that do not have values are ignored. If the value does not incorporate multiple lines. To specify the Request ID for join forms. Each of the following formats can be used in plain text. For example.Using label/value pairs in templates In the previous example. An example of a request ID label/value pair is RequestID:0000012345. Only fields that have values are used in the request. the label/value pair can be written as follows: Label:Value Chapter 5 Using email templates 153 . Basic format The basic format is the simplest. see “Configuring incoming mailbox security” on page 39. The passwords and security keys are encrypted in the AR System Email Messages form. and RequestID. You can associate a label with a constant value or a variable value. A key is required to use the Modify action. a join form Request ID might appear as TT000567|TT000890. 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. 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. then the Key label/value pair must be present in the incoming email message. Aliases for the Key label are Encryption Key and Encryption. An example of a Key label/value pair is Key:testKey. or XML documents. Label/value pair formats Your email must use specific syntax for label/value pairs so that the parser can extract the required information. HTML. EntryID. use the Request IDs of the forms referenced by the join form separated by a vertical bar. Key label If your incoming mailbox is configured to require a security key. 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. 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.6. The label and value do not have to be left justified. however. You can associate a label with a variable also..04 TIP You should use the [$$ . and the value tag represents the value. Strictly speaking. In HTML. The name tag represents the label. You do not have to surround the label with any special characters. The corresponding fields can be used in situations where input is required from the user. and can be prefaced by text on the same line. you do not need to use this multi-line syntax for all label/value pairs. 154 BMC Remedy Email Engine Guide .. You can still use the Basic format within the HTML document. The email client must allow or support the ability to edit HTML fields directly. To view a template using XML. 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. see “Sending outgoing email in HTML” on page 77. 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. 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. but it is a good practice to adopt if you think the values in a variable might exceed a single line. $$] variable syntax when the Email Engine needs to parse multi-line values.BMC Remedy Action Request System 7. an editor automatically generates the correct format when filling in any missing field values. 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. This field can give the user the ability to select the parameters that are valid and those that are not. the Action label has possible values of Modify. radio buttons can contain several sets of tags that comprise one instruction label and several values. Submit. and the value tag will contain a corresponding value.” The resulting label/value pair would be Action:Submit. such as Query. 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. In the following example. the label and value is not used because the word “checked” is not included in the definition. such as Action. <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> Chapter 5 Using email templates 155 . The selected value would be determined by the word “checked. Checkbox buttons Checkbox buttons allow you to design a document where there are several possibilities. Radio buttons Radio buttons allow you to design a document where the user can select from a given range of possibilities. The name tag contains a label. and Query. An example follows: <input type="checkbox" name="Label" value ="Value"> or <input type="checkbox" name="Label" value ="Value" checked> In the first example. Unlike a text field where only one set of tags between the <> markers represent a label/value pair. but those possibilities are not grouped together.Using label/value pairs in templates Text field In HTML. 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. the label and value is used because the box was checked. The values for the radio buttons would be Submit and Query. But in the second example. The tag containing the word “selected” determines the label/ value paid to be used. Submit.BMC Remedy Action Request System 7. As a result. 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. The menu field also allows the user to specify different visible text in the field with the correct field values defined underneath. 156 BMC Remedy Email Engine Guide . see “Creating an email content template with Submit and Query actions” on page 226.6. This allows you to use existing AR System field values to define the value of a variable.04 The type is a select HTML field. 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 label is Action. If the parameter is defined again after an action statement. see page 153. you do not have to repeat parameters. and the values are Modify. Content templates for new outgoing email. The name of the variable can be the same as a AR System field. The variable is defined as follows: #$$variable_name$$# When used in a label/value format. 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. then that parameter takes precedence over the global parameter for that action only. The variable is replaced by a value at execution time. use the following syntax: Label:[$$#$$Value$$#$$] For more information about label/value formats. Result templates for incoming email. The template for new outgoing emails is used as a content template. and Query. Variables can be used in place of values in the label/value pairs in templates. The variables are defined by values of the fields in the entry that triggers the notification. 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. For more information. for each instruction. such as login information or form names. Variables Variables allow the administrator to create generic templates. so there are no restrictions if used in the context of a AR System form. 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. For more information. For more information about how to do this. and qualification must be supplied. the variable is replaced with the appropriate value. For outgoing emails. If any one of these items is missing. For query information to be used. see “Using variables with notifications” on page 158. a form. resulting in a query as follows: Query:[$$’Last Modified By’ = “User” AND ‘Modified Date’ > “21/01/ 2004”$$] Chapter 5 Using email templates 157 . 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. this variable could be associated with a value as follows: !modified_date!:[$$21/01/2004$$] After the parser has extracted all the required information. For specific examples. Step 2 If you do not supply an attachment in the Values attachment field. the message creation will fail. see “Using the Attachment Alternatives tab” on page 86. the query information is used to generate the message. server.Using label/value pairs in templates In content templates used for outgoing emails. see “Using the Variable Replacement tab” on page 83. the attachment is used to determine the values for variables contained in the template. the information is used to determine values for variables contained in the template. 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. variables for field values must use the field database name. not the field ID. but your content template contains a query to obtain information to substitute in the email. Step 3 If you do not supply field values. the template variables for field values must use the field’s database name (not the field ID) as the variable name. Login. They do not work for Login or Server labels. Password. Using variables with notifications When creating templates to be filled in using notifications.04 NOTE Variables can be used only for form field values and qualifications. For example. For example. Global fields (fields before the Action label) cannot be substituted. 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.6.USER$$# 158 BMC Remedy Email Engine Guide . This is because the server uses the field name (database name) to assign the values in the AR System Email Messages form. Schema. 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 variable Login: #$$Joe User$$# would not be correctly parsed by the Email Engine and would return an unknown user error.New. Only local fields (fields after the Action label) can be substituted. Labels like Server. or Key are considered to be global and cannot be substituted.BMC Remedy Action Request System 7. 1952 AD. day. 2004). Reserved variables The Email Engine uses reserved variables to place the results of executing an email. So. 06/18/04). depending on your locale.Using label/value pairs in templates NOTE Do not use the Request ID to return entries from display or vendor forms in a notification. and year (for example. The following formats are valid: #$$Action. The order of each component is based on the Regional Options properties in the Control Panel. dd/mm/yy is not valid and will not work. such as Submit or Query. 31/01/04 will work as a short date if your locale is set to dd/mm/yy. An alphanumeric date that includes the day of the week. You can use reserved variables in Result and Status templates. Jan 12. for example. 1952. 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. #$$Action. Tuesday. Friday. Reserved variables fall under two main categories: Action information—Useful when creating a template that will contain the results of executing the associated action. but not in Content templates. in the countries where the valid value is mm/dd/yy. June 18. The format 31-Jan-04 will not work. The order of each component is based on the Regional Options properties in the Control Panel. and year (for example. but it also will not return the Request IDs. month. They can be defined in a Result template with variables that define the fields of a specific form. 2004 or January 31. As a result. You can see examples of valid date format values when you open Regional Options on your Control Panel for long and short dates.Name$$#—The action value.Number$$#—The position of the action within the entire execution list. especially when the dd part is greater than 12. 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 system will not generate errors. day. MEDIUM Longer numerical date description. 2004. but you can use Jan 31. April 12. Chapter 5 Using email templates 159 . Completely specified numerical date description. LONG FULL You cannot mix different locales for short and long formats. not mm/dd/yy. 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. for example. New. #$$ActionStatus. #$$ActionStatus. Error. for example: 15.Type$$#—The type of error.USER 15. (This reserved variable is valid only for User Defined Instruction templates.0.TIME You can also use numeric values.) Status information—Used to store the results of system-generated errors. #$$Action. This particular email uses the HTML status template found on page 142.Text$# #$$ActionStatus. for example: Status-History.AppendedText$$#—The associated appended text.New.USER The USER and TIME identifiers are case sensitive. These are also values that you would define in a status template.USER Status-History.6.Query$$# —The qualification (if any) associated with the instruction. Figure 5-7 displays an email that includes these reserved variables for status information. Number$# #$$ActionStatus.New.0. #$$ActionStatus.04 #$$Action. Figure 5-7: Reserved variables for status information used in outgoing email #$$ActionStatus.AppendedText$# The following rules apply for specific Status History information in the templates: You must use the fully qualified status history name. 160 BMC Remedy Email Engine Guide .Type$# #$$ActionStatus.Text$$#—The message text. Warning. The following formats are valid: #$$ActionStatus.Number$$#—The error or warning number.USER Status-History. such as Severe.BMC Remedy Action Request System 7.Form$$#—The name of the AR System form involved in this action. they are common to all forms. 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 required field and there is no default value defined for it. 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 Chapter 5 Using email templates 161 . Storing templates in the AR System Email Templates form When you create or export templates. an error will result. Comments are optional.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. Leading and trailing blanks are ignored when the Email Engine reads a value. If the user does not enter a value into a field that has a default value defined. then the default value is loaded. Values can be entered anywhere after the delimiting character. the default encoding of the local system is employed. It is useful to enter a description indicative of the function of the template. you should add the graphic file as an attachment. and choose Add from the menu that appears. 10 (Optional) Enter a description. The Add Attachment dialog box appears. 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. 162 BMC Remedy Email Engine Guide .04 To add a template to the AR System Email Templates form 1 Create or export your template.htm. The name of the attachment is displayed in the Template Name field. 4 Select the template format (Text or HTML) from the Template Format list. 3 Click the Template Information tab. 11 Click Save. 6 Right-click in the attachment pool. 5 Specify the Encoding so that the Email Engine can parse the templates. For example: template_attachment1.) If an HTML template contains a reference to a graphic file. to template1. 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. The system assigns a Template ID number to the template.BMC Remedy Action Request System 7. For more information. If you leave the Encoding field empty.6. WARNING You can only use graphic type files as attachments. (The Template ID field is hidden. 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. for example. 7 Browse to the template file you want to add and select it. see the following section. 8 Click Open.htm. and click the edit button next to the Template Name field. You can edit the file name. 2 Open the AR System Email Templates form in new mode in BMC Remedy User. 9 Select the item in the attachment pool. 5 Click the Template Attachments tab. Chapter 5 Using email templates 163 . The AR System Email Attachments form opens. This activates the buttons on the Template Attachments tab to add attachments to your template. Figure 5-9: The AR System Email Templates form—Template Attachments tab Add Attachment button 6 Click the Add Attachment button. 2 From the Template Format menu. choose HTML. 4 Click Save.Adding attachments to HTML templates NOTE The Email Engine does not support linking your HTML template to a cascading style sheet. 3 Add a template file as an attachment. To add attachments to HTML templates 1 Open the AR System Email Templates form in new mode in BMC Remedy User. The name of the template attachment is displayed. you can also click and drag an attachment to the attachment pool. 11 Select the item in the attachment pool. and click the edit button next to the Attachment Name field. The Add Attachment dialog box appears.jpg files) with a template and use the same name for each image. NOTE If you attach multiple images (such as . If you are using a Windows system. and choose Add from the menu that appears. 13 Your attachment will be added to the list in the AR System Email Templates form. 9 Browse to the file you want to add and select it. (The Attachment ID field is hidden.gif or . For example: template_attachment1. The Email Engine will give the template attachment an ID. The file is added to the list of attachments on the AR System Email Attachments form. 12 Click Save.htm You can edit the file name.04 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. 10 Click Open. 14 Click Save in the AR System Email Templates form. the Email Engine will use only the first attachment. 8 Right-click in the attachment pool.BMC Remedy Action Request System 7.6. You might need to right-click and select Refresh to see the attachment listed.) 164 BMC Remedy Email Engine Guide . The AR System Email Attachments form closes. Your attachment is added to the list in the attachment pool. The attachment appears on the attachment list. 4 Click Search to locate the attachment. click the arrow next to the blank field at the bottom of the pane. 2 Select the attachment.Adding attachments to HTML templates 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. The AR System Email Attachments form opens (see Figure 5-10 on page 164). Chapter 5 Using email templates 165 . 3 Click the Add Existing button. The attachment is deleted from the list. 4 Click Save. Deleting an attachment To delete an attachment 1 Click the Attachments tab in the AR System Email Templates form. 4 Click the Refresh Table button to refresh the table in the Attachments tab. 3 Click the Modify Attachment button. You also can modify the Attachment Name. 3 Click Delete Attachment. 6 Click Save. 2 Select the attachment you want to delete. 5 Modify the attachment as required. 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. 04 Exporting templates with attachments to another server You can export an HTML template from one server and then import the template onto another server.1 or earlier “as is” with release 7. 3 To guarantee that no other form is used for email submissions. 3 Copy the attachments associated with the template from the source server. Email Action for your incoming mailbox is set to Parse. set Force Default Workflow Form to Yes.00 or later. However. Preparing email templates after an upgrade If you have upgraded from BMC Remedy Mail Server (release 5. see “Sending incoming email with user instructions” on page 167.0. you might have to modify your existing templates to use the features in release 7. if you want to use your original templates for your incoming mailbox “as is” without using the 7.0. To export templates with attachments to another server 1 Export the HTML template from the AR System Email Templates form on the source server. 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. user password. Use Original Template Format is set to Yes.00 and later email template features. see the “Use Original Template Format” feature on page 34. Use Supplied User Information field is set to Yes.1 or earlier). or form name.0. 4 Manually add the attachments to the template in the AR System Email Templates form on the target server. To use your old email templates after an upgrade to Email Engine 7. For more information.6. perform one of the following tasks: Modify the template to include these parameters and values. for example.BMC Remedy Action Request System 7.00 or later.00 and later. 166 BMC Remedy Email Engine Guide .0. For more information. 4 If the original templates do not include a user name. set the Default Workflow Form to that form name. 2 If only one form is used for email submissions. the ability to use HTML in your templates. 2 Import the template into the AR System Email Templates form on the target server. Create a template that includes one or more of these values with a user instruction. there is a configuration setting that allows you to continue using email templates from release 5. 3 Email Engine Email Server Template associated with user instructions. Templates provide generic layout for similar emails that are sent from or into the Email Engine. Chapter 5 Using email templates 167 .Sending incoming email with user instructions Sending incoming email with user instructions A good analogy for understanding user instructions is that they are “macros” for email. Every user instruction must be associated with an email template. Figure 5-11: Overview of using instruction templates 4 User sends email with user-defined instructions. 2 Creates user instructions. User-defined instruction templates automate actions to make it easy to perform common user actions. 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. AR System Server Primary Configuration 5 Results. variables. and so on. you can create predefined submit and query actions with these instruction templates. Figure 5-11 on page 167 provides a sample scenario of how to create user instructions for your user community. 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. Like macros. simplifying Email Engine interactions for users. Underlying Database 1 Admin creates and stores email templates. These custom actions are called user instructions. BMC Remedy Action Request System 7. and then attaching the . TIP Test the template by sending email to the incoming mailbox and see if it returns the expected results. and name the file with an .arm) that queries all urgent records in the TestSecurityForm form.arm extension. Step 3 The administrator associates the template created in step 1 with the user instruction name.04 Creating user instructions involves the following tasks: Step 1 The administrator creates a template.arm file to an entry in the AR System Email Templates form. see “Creating templates” on page 143. 168 BMC Remedy Email Engine Guide . and then adds the template to the AR System Email Templates form. Step 5 As a result. Creating and storing a template for use with user instructions As an administrator. Step 4 The user sends an incoming email that contains the user-defined instruction (Action label/value pair) to the Email Engine. you can use a text editor to define templates by creating a text file with an extension of . 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. For more information. To create templates for use with user instructions 1 Use a text editor to define a template. Schema: TestSecurityForm Server: polycarp Login: Demo Password: Action: Query Format: Full Header Template: Header_Urgent. and the associated template is then executed.6. The following example is a template file (IN_Install_AllUrgent. the Email Engine constructs a message according to the template instructions and sends the message to the user.html Result Template: Default Content Qualification: 'Status' <= 2 AND 'Impact' = 3 A template can contain one or more instructions. 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. The user instruction template looks the same as any other template.arm. and complete the form as follows: 1 Do not enter a template ID. open the AR System Email Templates form in New mode. open the AR System User Instruction Templates form in New mode. The system will create the unique ID in the Instruction Template ID field when you save the entry. footer.Sending incoming email with user instructions 2 In BMC Remedy User. NOTE You can associate more than one user instruction with a template containing one or more instructions. and result templates that are used with your template. Chapter 5 Using email templates 169 . Figure 5-12: Storing a template 3 Attach your IN_Install_AllUrgent.arm file to an entry in the AR System Email Templates form. you must associate a name with the User Instruction by creating an entry in the AR System User Instruction Templates form. Creating user instructions After storing your templates. Your UrgentRequests template was created and now stored. The User Instruction name will be used as a value for the Action Label in the email the user sends to the incoming mailbox. 4 Click the Template Attachments tab to add any header. To create a user instruction In BMC Remedy User. 5 Save your changes. 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). 170 BMC Remedy Email Engine Guide . To send a user instruction 1 Create a new email message in your mail tool. select the template that contains that actions you want to associate with the user instruction. (See “Creating and storing a template for use with user instructions” on page 168. for example.6. 4 Send the email. 3 Enter the user instruction in the email. You can use only templates that are stored in the AR System Email Templates form. This value is used to identify this template when used in an incoming email. 4 Enter a character string value for the Instruction field.04 2 From the Template Name menu. 2 Address the email message to the incoming mailbox. for example. Urgent. UrgentRequests.) 3 To restrict the user instruction to one incoming mailbox. 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.BMC Remedy Action Request System 7. select a mailbox from the Mailbox Name menu. 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. Templates and user instructions can make it easier for your users to interact with the Email Engine. Instead. 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. Figure 5-14: The email response to a user instruction After receiving an incoming email. 2 Retrieves the associated template from the AR System Email Templates form. as shown in Figure 5-14. reducing the need for them to learn the Email Engine syntax.Sending incoming email with user instructions 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. 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. all they need to do is use the user instruction name as the value of the Action Label. Chapter 5 Using email templates 171 . 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).6. 2 Retrieve the database name or field ID between the exclamation marks in the template. For example.04 Using variables with user instructions You can also use variables with user instructions.BMC Remedy Action Request System 7. 172 BMC Remedy Email Engine Guide . Variables are useful when you need to send different values for the fields to submit an entry. 3 Substitute the field with that database name with the value sent in the email. The Email Engine will then: 1 Match the string between exclamation marks in the email with the variable name in the template. you can create a user instruction that submits information into the User Instruction form. 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 .Chapter 6 Troubleshooting This chapter contains troubleshooting information. as well as email system environment problems.) Error and system status logs The AR System Email Error Logs form stores error and system status information. 174 BMC Remedy Email Engine Guide . if they were sent.04 Troubleshooting outgoing email You will find the AR System Email Messages form especially helpful in troubleshooting outgoing email. (System generated emails are also called non-delivery reports [NDRs]. the email body will be in English only. Performing a search in the form lets you see the current status of email messages. for example.BMC Remedy Action Request System 7. if outgoing messages are being processed. Figure 6-1: Status of email messages NOTE If the Email Engine sends system-generated email (for example. due to a “bounced” email). or if there was an error.6. This information can be useful in troubleshooting email transmission or email formatting problems. (The email is included in the logging message as an attachment. and email forms.) All outgoing email. Date and time the Email Engine was started or stopped. Internal Email Engine errors. the entry created in the Email Error Logs form appears.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. TIP You can access the Email Error Logs form from the BMC Remedy User Object List or the Email Messages form. (The email is included in the logging message as an attachment. Chapter 6 Troubleshooting 175 . Changes to the configuration of the Email Engine. 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. logs. System status logs include information about: All incoming emails.) Connection status information for email servers. Connection status information for the AR System server containing the configuration. For more information. AR System API errors. see “AR System Email Error Logs form” on page 240. When you set this logging level.04 Email transmission or instruction failures When an email transmission fails or an instruction cannot be executed.6. See the Optimizing and Troubleshooting Guide. could not be found on the server—either the form name was entered incorrectly. the system generates an error message and stores it in the AR System Email Error Logs form.” page 51. In the following sample error message. 176 BMC Remedy Email Engine Guide . “API log. 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. only severe issues are written to the logs.BMC Remedy Action Request System 7. The higher levels provide more detailed information. or the form does not exist. if the system runs out of disk space) are logged. SEVERE The minimum logging level for Email Engine is SEVERE. referenced in two instructions. Internal Email Engine errors Any internal problems with the Email Engine itself (for example. a form called XYZForm. further to that provided by the lower logging levels. Logging levels Information added to the logs at the minimum logging level (SEVERE) also appears in logs created by using the maximum level (FINEST). Examples of errors include instructions that see a nonexistent form or an invalid server name. Logs created by using this level help trace the flow of execution easily.count = 1 File to where logs are made.logging. Handler Specific Properties java. which means all logs are to be sent to the output.Debugging options for the Email Engine INFO INFO is the next logging level for the Email Engine. but file logging can also be switched on. In this example.FileHandler. Chapter 6 Troubleshooting 177 . all console output is directed to emailEngineInstallDir/logs/emaild. Number to start with.FileHandler.logging. Maximum size of the log file in bytes.x logging. 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.util. If the file size exceeds this length. see “Fixing common problems with the email engine” on page 198.properties file that you use for debugging the Email Engine is usually found in the Java lib directory. This is appended to the end of the file name. In UNIX.util.level = FINER Definition Sets the places where logs can go.logging.util. Note: Use this option with care because the contents of the AR System Email Error Logs form can become very large.logging.5. java. You can set the logging level to Finer in the Java logging.properties file to obtain every log message generated by the system. Enables file logging with console logging.FileHandler.logging. it has been set to send logs only to the console.limit = 50000 Handler Specific Properties java.sh_log.pattern = %h/java%u.ConsoleHandler Global Property Handlers handlers = java.FileHandler. For specific issues.util.FileHandler. a new file is created. You can also use the keyword ALL. as it is specified by Java 1.log Handler Specific Properties java. Logging level for the file output.ConsoleHandler Global Logging Level java.logging. You can reference the Java documentation on this format. 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.util.util.logging. If there is no entry in the logging.logging.level = INFO main application level includes the modules unless you specify otherwise. the level for the file handler will be ignored and also set to INFO. or WARNING.level = FINER ReceiverModule. INFO). Note: The level for one of the outputs must be at least FINER.SimpleFormatter with console logging.ARSystem Handler.arsys. Console Handler Specific Properties java.logging.SimpleFormatter Main Application Level Level for the entire Email Engine. then you will see only FINER information in the log for the Receiver module.level = FINER SenderModule.logging.bmc.moduleName. You can specify the logging levels for the various modules independently from the entire Email Engine logging level.util.emaildaemon.emaildaemon. then the system defaults to the application level (that is.6.forma tter = java.logging.BMC Remedy Action Request System 7.level = FINER ExecutionModule. You cannot disable this handler.ConsoleHandler.ConsoleHandler. because this level is INFO.bmc. r = java. Module Levels com.util. and you can set the levels for the different modules independently. INFO.util.level = FINER CreatorModule. This level will be used for all logs originating from that particular module and only that module. This level could also be overridden if the application level defined previously is higher.level = WARNING Level for the outputs to the BMC Remedy Email Error form. This setting for the com. if the main application level is set to INFO and you set the level for the Receiver Module to FINER.FileHandler. You can override this behavior by adding one of these module levels. for only the modules you are interested in troubleshooting. to actually see the log. If the main application level is SEVERE.bmc. then specifying that level as FINER.properties file for a particular module.arsys. For example. or you can Handler Specific Properties java. then this level overrides that level for the given output.arsys.04 Table 6-1: Debugging options for the Email Engine (Sheet 2 of 2) Setting Definition Use an XML formatter to format the output.level = FINER Levels for application modules.logging. Console Handler Specific Properties java. level ConfigurationModule. then logs for more than one module will be allowed.level = INFO XML formatter for console logging. These application modules allow you to combine main application and module logging. If you add more than one module level. Application Levels com.util. such as the ConsoleHandler. FINE. In this example.logging.level = FINER MonitorModule.util.emaildaemon.formatte use java. then only module logs with a level of SEVERE are allowed. 178 BMC Remedy Email Engine Guide . If a level for one of the outputs is lower than this setting.util.XMLFormatter Logging level for the file output. util. When the Email Engine is installed. Chapter 6 Troubleshooting 179 .properties file You can change the logging levels of the email engine debugging options at runtime by using the following command: java -jar EmailAdminAgent.” Following the UNIX convention. Also. parsing instructions. and password. the EmailDaemon. “email daemon” is used to describe background processes launched at start-time. user name.” the use of various threads to carry out different tasks like sending and mails.level in the debuggingOption when using it in this command.level = FINEST java.properties for the JRE being used: com.properties file TIP The term “email daemon” is frequently used when discussing the internal components of the Email Engine.ConsoleHandler. and so on. For the most part. the file you use to set parameters for the Email Engine is called EmailDaemon. email “handlers.properties file is created in the Email Engine installation directory and is populated with the name of your organization’s email server.emaildaemon.bmc.properties. The main purpose of the EmailDaemon.Using the EmailDaemon. these background processes are usually called “daemons.properties file is to identify the AR System server your Email Engine communicates with.” whereas for Windows they are called “services.level = INFO Using the EmailDaemon. In UNIX. For example.debuggingOption. to change the logging level at run time you must set the following in values in logging. the Email Engine as synonymous with the email daemon.logging.jar setLog debuggingOption loggingLevel IMPORTANT Make sure you do not include .arsys. BMC Remedy Action Request System 7.6.04 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 changes—for example, if you need to change a server name or a TCP port—the 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 BMC Remedy Email Engine Guide Using the EmailDaemon.properties file 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. Chapter 6 Troubleshooting 181 BMC Remedy Action Request System 7.6.04 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 Incoming All Supported Incoming All Supported True (Default) Outgoing All Supported False Outgoing All Supported 182 BMC Remedy Email Engine Guide Using the EmailDaemon.properties file 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 Chapter 6 Troubleshooting 183 BMC Remedy Action Request System 7.6.04 Table 6-3: Performance and configuration settings for the Email Engine (Sheet 3 of 10) Settings Definitions Values Related Related Functiona Protocol lity 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. true—the 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. True (Default) Outgoing All Supported False Default value: 100 Incoming All Supported 184 BMC Remedy Email Engine Guide Incoming All and Supported Outgoing Chapter 6 Troubleshooting 185 .Using the EmailDaemon. and another instruction is to be added.bmc. the cache already contains 15 instructions. then the oldest instruction is removed to accommodate the newest one. com. com.Interval property.arsys.ema Specifies the message queue size (number Default value: 100 ildaemon. This reduces the traffic to the AR System server and improves the performance. Note: If any changes are made to the Default value: 20 Incoming All Supported AR System Email Instructions form.arsys. the instruction cache is flushed based on the setting of the serverName. but the Execution module reads the message from the message queue instead of from the server.properties file 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. ionCacheSize If the value of this property is set to 15. the email engine only processes these mailboxes. The value of this property should contain comma-separated mailbox names.instruct stored in the cache.Incoming of emails). If you do not specify a value. and the Execution module reads messages from this queue to parse and execute. this property s specifies which mailboxes should the email engine process.ema If you run multiple instances of the email ildaemon.Mailboxe engine on a single server.arsys.ema Specifies the number of instructions to be ildaemon. MessagesQueueSize The Receiver module writes messages to the queue.bmc. which is used to improve performance.bmc. the email engine processes all of the mailboxes configured for the server. The Receiver module still writes messages to the server in AR System Email Messages form. bmc.MailboxP ollingUnitIsMinut es Specifies whether the polling interval is to be considered in minutes (as configured in AR System Email Configuration) or seconds. you can create workflow for this form to process such messages separately.emaildaemon.xls The size limit is not imposed on files whose extensions are not specified by using MaxAttachSizeFileExtensions.arsys.pdf.emaildaemon.ema Specifies the attachment types that you ildaemon.bmc.arsys. .arsys.arsys. to set the maximum size of .04 Table 6-3: Performance and configuration settings for the Email Engine (Sheet 5 of 10) Settings Definitions Values Related Related Functiona Protocol lity com. The email engine interprets the value of this property as follows: true—Consider the polling interval in minutes. These properties ns must be used together to impose limits on email attachments of specific file types.bmc.arsys. whereas ildaemon. Optionally.ema ildaemon.6. For example. MaxAttachSizeFileExtensions=doc .pdf.MaxAttac MaxAttachSizeFileExtensions hSizeFileExtensio specifies the file types by using commaseparated extensions. hSize MaxAttachSize specifies the maximum com.xls attachments to 1000000 bytes (1 MB). Note: Whatever measure of unit you select True (Default) Incoming All and Supported False Outgoing applies to all configured mailboxes that are enabled. false—Consider the polling interval in seconds.BMC Remedy Action Request System 7. True Incoming All Supported False (Default) 186 BMC Remedy Email Engine Guide .doc. use the following syntax: and com.bmc.bmc. and . Email messages with attachments that exceed this limit are logged to the AR System Email Error Logs form.ema size limit for attachments.MaxAt tachSize=1000000 com.MaxAttac want to permit in an email message and the maximum size of each attachment. com. resume.bmc.bmc. which might reduce the performance. the hardware configuration.ema The email engine interprets the value of ildaemon.Monitor checks to see if all the threads are functioning properly. If you set a very high value.MBOXFrom this property as follows: LineWith-At-Thetrue—Email Engine fetches only those Rate-Sign messages that contain the @ sign in the “from line” (from address). com. it restarts the thread. The optimum number of message queue size to be specified depends on the load on the email daemon. Item To delete sent messages from the Email Messages form.arsys. com. 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. = 1100 This feature is used with the EmailAdminAgent. com.bmc. com.properties file Table 6-3: Performance and configuration settings for the Email Engine (Sheet 6 of 10) Settings Definitions Values Related Related Functiona Protocol lity com.jar file to stop.arsys.NumberOf that the email daemon uses for each SenderThreads outgoing mailbox.ema Specifies the number of sender threads ildaemon. 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.ema Specifies the size of the queue that the ildaemon. Default value: 1100 Incoming All and Supported Outgoing True (Default) Outgoing All Supported False Chapter 6 Troubleshooting 187 .SaveSent Email Messages form after sending. or change logging level of the email engine at runtime.RMIPORT method invocation (RMI). false—Email Engine fetches all the messages.ema Specifies the interval in minutes between ildaemon. suspend.arsys.Outgoing email daemon maintains for outgoing MessagesQueueSize messages.ema Specifies the port number for remote ildaemon. com.bmc. set this property to False.arsys.bmc.Using the EmailDaemon.ema Specifies whether to retain messages in the ildaemon. and so on. the database is queried too often.arsys.bmc. Note: This value is used to determine when Default value: 100 Outgoing All Supported to query the database.arsys. Note: If any changes are made to the AR System Email Security form.Interval following: Configuration updates (for example. and another key is to be added.security stored in the cache. com. if you modified records in the AR System Email Mailbox Configuration form) Updates to the templates (for example.arsys.arsys.serverNa engine must use.ema Specifies the TCP port number that the ildaemon.ema Specifies the language that the email ildaemon.bmc.bmc. com.serverNa which to check with the server for the me.arsys. CacheSize If the value of this property is set to 15.SendEmai query at a time.BMC Remedy Action Request System 7.serverNa requires authentication information before me.serverNa AR System server uses if you have me.arsys.Language com.Authentication handling requests.ema Specifies the number of security keys to be Default value: 20 ildaemon.bmc. then the oldest key is removed to accommodate the newest one. com. if you added or deleted any field on any form) com.Interval property. 100 lSetSize com.Servers that the email engine interacts with. if you modified templates in the AR System Email Templates form) Any changes done to the forms on the server (for example.ema Specifies the number of outgoing emails to Default value: ildaemon.TCP BMC Remedy AR System portmapper.arsys.04 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.arsys.6. the security cache is flushed based on the setting of the serverName.bmc.ema Specifies the RPC port number that the ildaemon.ema Specifies the interval in minutes after ildaemon.ema Specifies a string if your AR System server ildaemon.bmc.bmc.bmc.RPC configured a private server to be used with the email engine.serverNa AR System server uses if it is not using the me.ema Specifies the name of the AR System server ildaemon.arsys. the cache already contains 15 security keys.arsys.bmc. me. Default value: en_US Default value: 30 Outgoing All Supported 188 BMC Remedy Email Engine Guide . com. In case of an SMTP timeout. If you want the email engine to use this property. it works only when SMTPTimeout is set to true.arsys. Note: SMTPTimeoutPeriod is dependent Outgoing SMTP on SMTPTimeout. SMTPTimeoutPeriod is not used by default. com. com. you must add it to EmailDaemon. Note: See “Recommendation for using the SMTP timeout properties” on page 192.properties and set its value to any positive integer (upper limit depends on the platform).properties file Table 6-3: Performance and configuration settings for the Email Engine (Sheet 8 of 10) Settings Definitions Values Related Related Functiona Protocol lity com. If you add the property but do not specify a value.properties and set its value to true. If you want the email engine to use this property.ema Specifies whether to wait before cancelling ildaemon. In case of an SMTP timeout.SortMess with a higher priority setting first. SMTPTimeout is not used by default.SMTPTime an attempt to connect to the mail server out and generating an error. If you add the property but do not specify a value. it is considered as false.ema Specifies whether to process messages ildaemon. ages True Outgoing All Supported False (Default) Chapter 6 Troubleshooting 189 .arsys. Note: See “Recommendation for using the True Outgoing SMTP False (Default) SMTP timeout properties” on page 192. the email engine waits for this interval and then marks the queued message as an erroneous. you must add it to EmailDaemon.bmc.bmc. the email engine waits for the timeout interval and then marks the queued message as erroneous.bmc.Using the EmailDaemon.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. it is considered as half the polling interval that is set for outgoing mailboxes. The Execution module in the Email Engine handles both the parsing and execution of messages. and another template is to be added. the bulk API logging mode is used. instructions are not stored in the server. 190 BMC Remedy Email Engine Guide .arsys.bmc.ema Specifies whether to store instructions and ildaemon.6. izedLoggingMode If this property is not present in EmailDaemon. then the synchronized logging mode is used.Interval property. because all the email engine threads are suspended while processing the synchronized logs. Then. the email engine retains data in the Email Instructions and Instruction Parameters forms for troubleshooting. If this property is present in EmailDaemon. ildaemon. you must delete this data explicitly. If set to true. com.bmc.properties and its value set to true. com.arsys.ema Specifies the number of email templates to Default value: ildaemon.04 Table 6-3: Performance and configuration settings for the Email Engine (Sheet 9 of 10) Settings Definitions Values Related Related Functiona Protocol lity com.BMC Remedy Action Request System 7. Note: The email engine’s performance True Incoming All supported False (Default) Incoming All True Supported False (Default) and Outgoing might degrade when synchronized logging is enabled. If the value of this property is set to 15. There will be one message queue created for each Incoming mailbox.arsys. and control is restored to the threads only after the logging is over. Note: If any changes are made to the Incoming All Supported AR System Email Templates form. then the oldest template is removed to accommodate the newest one.bmc. Synchronized logging continues to occur periodically.properties. the cache already contains 15 templates. or if it is present but set to false.template be stored in the cache to improve the 20 CacheSize performance.StoreIns instruction parameters in the AR System tructions server.Synchron You can add it if required. the templates cache is flushed based on the setting of the serverName. By default.ema This property is not available by default. Note: The email engine checks for email True (Default) Outgoing All Supported False True (Default) Outgoing All Supported False addresses associated with display names only on the User form and not on the Exchange server.UseNameI that do not have email addresses associated fNoEmailAddress with them in the To. If the setting is true.arsys.arsys.ema Specifies whether to retain display names ildaemon. If the setting is false. so that it is retained.AdminAdd administrator. If a database transaction fails while storing an incoming message. resses the email engine forwards the original mail to this email address.UserChun from the User form) to retrieve from the kSize AR System server at one time. the <a href> tag is used. the URL is not enclosed in an <a href> tag. CC.bmc.ema Specifies the email address of the ildaemon. com.bmc. If the setting is true.URLWithH placed around a URL in an HTML refTag message.Using the EmailDaemon. the display names are removed from the To. Chapter 6 Troubleshooting 191 . or BCC fields.bmc. Note: This property can be used only when Default value: 5000 Outgoing All Supported Default value is Incoming All Supported set to the administrator address specified during installation.bmc.arsys.arsys. You can specify multiple addresses separated by commas. CC. com. or BCC fields. An example of a transaction failure could be when the database is full and cannot save anymore incoming email messages.properties file Table 6-3: Performance and configuration settings for the Email Engine (Sheet 10 of 10) Settings Definitions Values Related Related Functiona Protocol lity com. CC. the display names are not removed from the To. If the setting is false. com.ema Specifies the number of users (records ildaemon. This setting can be used to tune the email engine’s performance. the Email Engine does not capture the error out incoming email messages in the AR System Email Error Messages Form. or BCC fields.ema Specifies whether an <a href> tag is ildaemon. 192 BMC Remedy Email Engine Guide . The contents of the AR System Email Error Logs form can become very large. To avoid facing this issue. Creating email debug batch files Creating a debug email batch file by using the -Dmail.6. You accomplish this by setting the debug mode for the Java process that runs the Email Engine.debug=true debug mode can help resolve issues that might not show up in the email error log. This seems to be a JavaMail issue (SW00364840 in the Release Notes) for which we do not yet have a workaround. However.BMC Remedy Action Request System 7. 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. messages marked as Error (in the Send Message field) are not sent consistently—some messages are sent successfully. If you use the SMTPTimeout and SMTPTimeoutPeriod properties. After a timed out connection is restored. while others are not. you might encounter problems with outgoing email messages. you might want to refrain from using these properties until a solution is made available. BMC recommends using a value that is optimum for your configuration. You might find this procedure useful for debugging the Email Engine in contrast to using the AR System Email Error Logs form.04 Recommendation for using the SMTP timeout properties If you use the email engine properties SMTPTimeout and SMTPTimeoutPeriod. bat file is C:\Program Files\BMC Software\ARSystem\AREmail.bat file.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/emaildaemon.debug=true option as follows: "%JavaPath%\java" -Dmail..Creating email debug batch files Debugging the Email Engine on Windows To enable the -Dmail. To debug the Windows Email Engine 1 In the EmailStart.0_11\lib\javamail.jar!/META-INF/javamail.jar.5.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.arapireleaseNum.mail.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/emaildaemon. perform the following steps.armapireleaseNum.emaildaemon.out to the end of the previous Java statement.00.bmc.jar com.jar.jar!/META-INF/ javamail. DEBUG: JavaMail version 1. change the directory to the location of the AR System install directory.activatio n. for example. loaded library Successfully connected.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp. This batch file adds debug information to the screen when the Email Engine is started from a command prompt.jar.00 Using JRE: 1.EmailDaemon The default location of the EmailStart. add the -Dmail.providers Chapter 6 Troubleshooting 193 .jar.jar. and run the new batch file.jar.arsys.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/imap.bat.jar.imap. 4 Open a command prompt.smtp. 2 Save the batch file as another name. emaildebug.arutilreleaseNum.5.pop3. Sample debug log The contents of a sample debug log follow. You can also direct the output to a file by adding > c:\temp\debug.0_11 Checking connection to server: polycarp .jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/imap.jar.jar!/META-INF/javamail..debug=true -cp emaildaemon. 3 Make sure that the Email Engine service is stopped in the Services window.debug=true debug mode option for Windows. C:\Program Files\BMC Software\ARSystem\AREmail>echo off Application has started Version: 07.jar!/META-INF/ javamail. pop3.MAPITransport. Inc].mapi.Provider[TRANSPORT.mail.0_11\lib\javamail.mail.MAPIStore=javax.Su n Microsystems.address.mail.sun.com]. mapistore=javax.com.Provider[STORE.mail.mapitransport.mail.mail.default.co m.io.pop3.sun.POP3Store.mapi.sun.mail.com.jar!/META-INF/ javamail.map DEBUG: java.mail.MAPITransport=javax.5.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.com.imap.IMAPStore.bmc.imap.mail. com.Provider[STORE.bmc.SMTPTransport. com.com].com. Inc].Sun Microsystems.Sun Microsystems.jar!/META-INF/ javamail.mail.pop3.com].smtp .mail.mapistore.com.jar!/META-INF/javamail.0_11\lib\javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/emaildaemon.bmc.SMTPTransport=javax.providers 194 BMC Remedy Email Engine Guide .POP3Store.Provider[STORE.sun.mail.map itransport.BMC Remedy Action Request System 7. Inc].SMTPTran sport.Provider[TRANSPORT.pop3.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/imap.smtp.jar!/META-INF/javamail.MAPIStore.mail.map (The system cannot find the file specified) DEBUG: JavaMail version 1. pop3=javax.S un Microsystems.mail.mail.Sun Microsystems.smtp. smtp=javax.jar!/META-INF/javamail.Provider[STORE.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/pop3.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/pop3. com. mail.Provider[STORE.IMAPStore.5.bmc.jar!/META-INF/ javamail.bmc.mail.mapi.mail.04 DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.com. Inc]} DEBUG: Providers Listed By Protocol: {imap=javax. Inc]} DEBUG: successfully loaded resource: /META-INF/
[email protected] PIStore.MAPITransport.map DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.mapi.address.providers DEBUG: successfully loaded resource: /META-INF/ javamail.mapi.mail.Provider[
[email protected]: C:\Program Files\Java\j2re1.Provider[TRANSPORT.default. com.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com.jar!/META-INF/
[email protected] DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/
[email protected][TRANSPORT.mail.IMAPStore=javax.sun .com.imap.com].sun .jar!/META-INF/javamail.address.mail. Inc].address.smtp.mail.com.mail.imap.imap.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/emaildaemon.pop3. mapitransport=javax.smtp.mapi.com.Sun Microsystems.mapistore. mail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/pop3. mapitransport=javax. Inc] POP3: connecting to host "essmail2"
[email protected] Microsystems. mapistore=javax.map itransport.jar!/META-INF/ javamail.map DEBUG: java.mapistore.providers DEBUG: successfully loaded resource: /META-INF/ javamail.FileNotFoundException: C:\Program Files\Java\j2re1.MAPITransport.Provider[STORE.POP3Store.mapi.com.Provider[TRANSPORT.mapitransport.mail.POP3Store=javax.pop3.address.pop3.MAPITransport=javax.sun. pop3=javax.mail.com].com.com.imap.mail.sun.sun
[email protected][STORE.Sun Microsystems.com.smtp .mapi.default.0_11\lib\javamail.com.map DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.com.sun.address.sun.com].0.mail.bmc. Inc].jar!/META-INF/ javamail.SMTPTransport=javax.Creating email debug batch files DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/imap.Provider[STORE.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.bmc.POP3Store.mail.Sun Microsystems.mail. com.bmc. Chapter 6 Troubleshooting 195 .jar!/META-INF/ javamail.smtp.mail.S un Microsystems. Inc].mail.address.POP3Store. com.mail.Provider[STORE.smtp.mail.com].pop3.0 (essmail2.mail.com) ready.sun .mapistore.imap.IMAPStore. Inc]} DEBUG: successfully loaded resource: /META-INF/ javamail.mail.com. com.smtp.mapi.jar!/META-INF/
[email protected]. Inc].SMTPTransport.MAPIStore=javax.address.mail.Su n Microsy stems.map (The system cannot find the file specified) DEBUG: getProvider() returning javax.jar!/META-INF/ javamail.IMAPStore=javax.Provider[TRANSPORT.sun.sun.mail.sun.Sun Microsy stems.bmc.com]
[email protected] DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.Provider[STORE.map DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.mail.imap.IMAPStore.com.mail.6249.mail.com.bmc. Inc].mail.pop3.io.co m.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/pop3.eng.pop3.bmc.5.Provider[STORE.Provider[STORE.mapi.mapi. smtp=javax.Sun Microsystems.SMTPTran sport.mail.mail.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com. mail.mail.jar!/META-INF/javamail.mail.Provider[TRANSPORT.imap.smtp.pop3.default.mail.bmc.jar!/META-INF/javamail.imap.pop3.MAPITransport.mail.MA PIStore. com.com. port 110 S: +OK Microsoft Exchange 2000 POP3 server version 6.Provider[TRANSPORT. Inc]} DEBUG: Providers Listed By Protocol: {imap=javax. debug=true -cp ${CP_PATH} com. name it JVM Option Number 4. 3 Create a new String Value.log file.debug=true debug mode option for UNIX. The debug log is available in the emailEngineInstallDir\Logs\stdout.path=${InstallPath} -Dmail. stop the Email Engine service.sh script from: exec ${JAVA_BIN}/java -Djava.sh script: -Dmail.0 signing off To generate debug log using the Windows Email Engine service 1 From the Services window. and navigate to HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > Email Engine > machineName > Parameters. Debugging the Email Engine on UNIX To enable the -Dmail.emaildaemon. 2 Open the Windows registry.bmc.emaildaemon. perform the following steps.library. To debug the UNIX Email Engine 1 In the emaild.6249.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1 3 Stop and start the Email Engine.arsys.BMC Remedy Action Request System 7.path=${InstallPath} -cp ${CP_PATH} com. add the following option to the line that starts the Java process in the emaild.arsys.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1 to the following content: exec${JAVA_BIN}/java -Djava.0. 4 Change the value of JVM Option Count to 5.04 C: USER stamps3 S: +OK C: PASS password S: +OK User successfully logged on.debug=true 2 Edit the emaild. and set its value to -Dmail.bmc.sh script.library. C: STAT S: +OK 0 0 C: QUIT S: +OK Microsoft Exchange 2000 POP3 server version 6. 5 Start the Email Engine service. 196 BMC Remedy Email Engine Guide .debug=true.6. Recipient ok Verified Addresses
[email protected]. Inc] DEBUG SMTP: useEhlo true.Provider[TRANSPORT.bmc.0 h1AKJZh09819 Message accepted for delivery Chapter 6 Troubleshooting 197 .com DEBUG SMTP SENT: DATA DEBUG SMTP RCVD: 354 Enter mail.com Hello cruiser. DEBUG: getProvider() returning javax. arg "" DEBUG SMTP Found extension "HELP".com [10. arg "" DEBUG SMTP Found extension "EXPN".11..bmc..0. arg "" DEBUG SMTP Found extension "SIZE".30.Sun Microsystems.6+Sun/ 8.4. arg "" DEBUG SMTP Found extension "DSN".1.Creating email debug batch files Example of outgoing email using SMTP The contents of a sample debug log for outgoing email follow.23].mail. 10 Feb 2004 12:19:35 -0800 (PST) DEBUG: SMTPTransport connected to host "cruiser". end with "..com DEBUG SMTP RCVD: 250-cruiser. Mon.sun. useAuth true DEBUG: SMTPTransport trying to connect to host "cruiser".mail.smtp." on a line by itself DEBUG SMTP SENT: DEBUG SMTP RCVD: 250 2.bmc. 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 "ETRN". arg "" DEBUG SMTP Found extension "8BITMIME". port: 25 DEBUG SMTP SENT: EHLO cruiser.1.5 .com ESMTP Sendmail 8.com. port 25 DEBUG SMTP RCVD: 220 cruiser.11. arg "" DEBUG SMTP Found extension "ONEX".0 .. Sender ok DEBUG SMTP SENT: RCPT TO: DEBUG SMTP RCVD: 250 2. arg "" DEBUG SMTP Found extension "XUSR".bmc.smtp. arg "" DEBUG SMTP Found extension "VERB".SMTPTransport . arg "" DEBUG SMTP: use8bit false DEBUG SMTP SENT: MAIL FROM: DEBUG SMTP RCVD: 250 2. BMC Remedy Action Request System 7. # tail -f emaild.5. A straightforward way to troubleshoot this problem is to verify that you have properly configured your incoming and outgoing mailboxes. Configuring mailboxes A common problem that users experience with the Email Engine is that they cannot send or receive email.0/j2se/jre/lib/ javamail.org] mbox: creating /var/mail/arsystem.sh_log DEBUG: java.mbox.map (No such file or directory) DEBUG: getProvider() returning javax.04 Example of incoming email using MBOX The contents of a sample debug log for incoming email follow.mbox.address.mail.io.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.mail.lock mbox: creating /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.d og@gnu. You can see the lock file get created—the file is read and saved.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem. and then the lock is removed.providers.lock mbox: creating /var/mail/arsystem.Provider[STORE.gnu. 198 BMC Remedy Email Engine Guide .6.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.FileNotFoundException: /usr/java1. The Email Engine can be a powerful and useful tool if configured and used correctly.MboxStore. The mail server is running. You entered the correct password for the email account in the Incoming Mailbox Basic configuration tab (POP3/IMAP4). 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). 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. the Email Engine service is launched as the local system account. 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. 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. If your mail server requires authentication. or the Exchange profile specified for this mailbox is accessible on the system the Email Engine is running on (MAPI).Fixing common problems with the email engine Testing your incoming mailbox If you were unable to test your incoming mailbox configuration successfully. see “Changing the form entry interval time” on page 44. NOTE The Email Engine might not immediately recognize changes you make to your mailbox in an effort to troubleshoot possible configuration problems. Chapter 6 Troubleshooting 199 . verify the following conditions: The Email Engine is running. Determine if the mail server requires authentication for messages to be sent. NOTE By default. 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). For more information. The Status field of the mailbox is to Enabled. The port number in the mailbox entry is the proper port number for communicating with your mail server. However. if you elected to configure a MAPI mailbox during installation. verify the following conditions: The Email Engine is running. Testing your outgoing mailbox If you were unable to test your outgoing mailbox configuration successfully. The mail server is running. such as stack traces and the exact exceptions thrown. but is stored in only one file called emaild. emailEngineInstallDir\Logs). but stdout.log and stderr. all console output is piped to the open console window. and then re-start it from the command line by using debug mode. The best way to troubleshoot these problems is by creating log files and examining your console output. This should be the first place you look to identify an issue. 3 Consult the console output to access more details. 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.sh_log. the output is located under the logs subdirectory of the Email Engine installation (by default.log contains normal output. see “Creating email debug batch files” on page 192. The location of the console output depends on how the application is executed and on which system.BMC Remedy Action Request System 7. Both files contain the console output. NOTE The Email Engine might not immediately recognize changes you make to your mailbox in an effort to troubleshoot possible configuration problems. 200 BMC Remedy Email Engine Guide . To use the Email Engine logs and console output 1 Stop the Email Engine.log contains any errors generated while the application was running.04 The port number in the mailbox entry is the proper port number for communicating with your mail server. such as the startup information and possible debug output. When the email daemon is executed on Windows as a service. You might find two files: stdout. For more information. 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. while stderr. when the Email Engine is started from the command line. see “Changing the form entry interval time” on page 44. 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.log. The email daemon always uses the AR System Email Error Logs form when logging errors and warnings.6. the console output is placed under the emailEngineInstallDir/ logs directory. 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). 2 Examine the AR System Email Error Logs form. For more information. On UNIX. (Recommended) For both Windows and UNIX. 5. 5 Enable the console output with the following handler property: handlers = java.level = INFO 7 Set the level for the entire application.arsys. which locates most problems with the Email Engine.level = INFO com. You might see dramatic improvements in performance. The level for the form logging should never be set lower than this.emaildaemon.emaildaemon.sh file is updated. Make sure that the following two lines are located in the logging. 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. Chapter 6 Troubleshooting 201 . try to modify the minimum and maximum settings. Otherwise.util.ConsoleHandler. located in the javaInstallDir/lib directory. You set this level with the following line: java. the level is usually set to INFO. the second line sets the level for logging to the AR System Email Error Logs form.properties file: com.ARSystemHandler. Defining a heap size for the Email Engine Release 7.level = INFO The first line sets the level for the entire application. on Windows Value in the emaild. you should adjust your heap size according to your memory needs.arsys.bmc.00 onwards.bat file.Fixing common problems with the email engine 4 Make sure that console logging is turned on in the logging.util.bmc. By default. the table will fill up very quickly and use unnecessary space. on UNIX If you run out of memory. and then stop and restart the Email Engine.properties file.logging.ConsoleHandler 6 Set the level for console logging. NOTE BMC cannot recommend the exact heap sizes to suit your environment.logging. 6. has the status set to Yes. users might find that email has not been sent or received.arsys.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. 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. The following troubleshooting sections describe some common scenarios and their possible solutions. For example. 202 BMC Remedy Email Engine Guide . the line for this setting might look like: java -Xms256m -Xmx1024m com.sh file to include the options: -XmsSize to specify the minimum heap size -XmxSize to specify the maximum heap size For example.emaildaemon.04 Changing the heap size on Windows You can change the minimum and maximum values for the Java heap size in two ways. In this situation.bat. 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 . 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. edit the emaild. but the status does not change to Error or Sent. If you use EmailStart. new email.BMC Remedy Action Request System 7.bmc.EmailDaemon Troubleshooting startup issues After installing the new Email Engine. the JVM Option Count will be 4. then edit the minimum and maximum Java heap size values in that file. ready to be sent. However.0 or higher.properties file. see “Updating the EmailDaemon.0 (or later) is mandatory for installation of the Email Engine to finish successfully. the installation program exits and you are reminded to install Java 1. a functioning email daemon outputs the following status information: Checking connection to server: ARSystemServerName . You might not encounter any problems if you start the Email Engine service while the AR System server is running.Fixing common problems with the email engine 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. Identifying invalid application service passwords When viewing the AR System Email Error Logs form.log (Windows) or emaild. To identify and correct an invalid password 1 Start the Email Engine from the command line. if you start the Email Engine service and the AR System server is not available for some reason.5. 2 Open the stdout. the most likely problem is that the Email Engine is not able to communicate with the AR System server. Typically.5. If you do not have the correct Java version. it might seem that the email daemon is not working at all.sh_log is not present. If you encounter ARERR 623. Further. these messages are displayed on the console. because you could not start the Email Engine service unless the AR System server was already running. This situation could occur when you restart the Windows system where the AR System server and Email Engine are installed. For more information about the EmailDaemon.sh_log (UNIX) file to note the JRE version used by Email Engine.5. NOTE Installing Java version 1. Application has started Version: emailEngineVersionNUmber Using JRE: JREVersionNumber Successfully connected If stdout. and the Startup Type for both services is Automatic. This problem did not occur in the earlier releases.0 (or later). Chapter 6 Troubleshooting 203 . then the Email Engine fails to connect with the AR System server and generates ARERR 90.log or emaild.properties file” on page 180. The JRE version should be 1.. When that password is changed at the server. you might have supplied an invalid application service password during installation. you might not find any errors.. you must change it for the Email Engine by updating the EmailDaemon. The Email Engine uses the Application Service Password to communicate with the AR System server.properties file. In this situation. 3 To fix the problem.TCP=4040 com.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. the Application Service Password you supplied during installation is incorrect.bmc. make sure to remove this parameter from the script afterwards.04 If the email daemon was unable to connect to the AR System server.arsys. To determine if a wrong AR System server is specified 1 Open the EmailDaemon. the search and replace functionality is required. You can also change the application service password by editing and then running the script. Because the file uses the server name in several places.properties file.ARSystemServerName.production.properties file. This updates the system with the correct password by applying the changes to the EmailDaemon..emaildaemon.BMC Remedy Action Request System 7.arsys.bat (Windows) or emaild.6. You can fix this problem by executing a search and replace on the contents of the EmailDaemon.properties file: com. ERROR (623): Authentication failed.emaildaemon. run the EmailStart. com.. 3 Check the connection to the AR System server if you are using a specific TCP port or RPC number. If you see this. 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 might see the following error: Checking connection to server: ARSystemServerName .sh (UNIX) script by passing the -p “applicationServicePassword” parameter. 5 Save your changes to the EmailDaemon. 4 Examine the AR System Email Mailbox Configuration forms to make sure that you have configured your mailboxes correctly. 6 Stop and re-start the Email Engine. Check to make sure that you have not disabled any of the mailboxes.properties file.properties file.bmc. 204 BMC Remedy Email Engine Guide . 2 Replace all references to the incorrect server name with the correct server name.TCP=4040). and restart the email daemon.emaildaemon.bmc.arsys.ARSystemServerName. Update these references as well in the EmailDaemon. Cannot connect. The console output should show that the email daemon has successfully connected to the AR System server with no errors. If you do so. 4 Confirm the email server supports the protocol you supplied. MAPI or SMTP.Session. Each protocol has a different default value. for example. 7 Check the User Name and Password. such as Microsoft Outlook Express.5. unless the mail server has been configured differently.mail. but incoming email is not logged and outgoing emails have not been sent. Use the following procedure to check the mail server.Session. errors should be logged in the form and on the console. assuming that console logging has been enabled properly.java:760) at javax.Fixing common problems with the email engine Determining problems with the mail server If the email daemon is able to connect to the AR System server.mail.mail.getTransport(Session. 5 Confirm the email server port. Some error messages you might encounter with the mailbox include: Unknown Host Exception Authentication Failed Exception Connect Exceptions.Session.mail. and you have specified MAPI as the protocol to use.java:628) Chapter 6 Troubleshooting 205 .Session getService SEVERE: mapitransport javax.java:685) at javax. 2 Open the entries for both the incoming and outgoing mailboxes.getService(Session.getTransport(Session. Windows—Fixing MAPI transport problems When using the Email Engine on Windows.mail. click the Set Email Server Port button to force this value to be the default for that protocol.00 Using 1. you might encounter the following MAPI transport error when starting the email daemon: Application has started Version: 07. Retype them if necessary.00. 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). check the value with your email server administrator. your primary email server is Microsoft Exchange. the problem is usually because the mailbox has not been configured properly in the AR System Email Mailbox Configuration form.NoSuchProviderException: mapitransport at javax. 3 Check the email server name. If this is the case. open the AR System Email Mailbox Configuration form in Search mode. To determine problems with the mail server 1 In BMC Remedy User. 6 If you are unsure. Confirm that you can ping or connect from the system by using an email client. such as Connection Refused In these situations.0_11 loaded library 8-Apr-2004 12:00:36 PM javax. 6.ThreadBase.run (ThreadBase. 3 On the second line.imap. This is the same location as the logging. To fix the MAPI transport problem (Windows) 1 Locate the javamail.mail.providers file in the lib directory of the JRE installation. class=com. NOTE This is not an issue.java:608) at com.BMC Remedy Action Request System 7.java:536) You typically see this problem when the Oracle JavaMail system does not know what transport setting to use for MAPI.imap.run(Thread.bmc.
[email protected]:103) at com. verify (or add) the following text: protocol=mapistore. These settings make sure that the JavaMail system uses the class created to support MAPI for both incoming and outgoing mailboxes.Thread.arsys. class=com.disable=false mail.emaildaemon. NOTE The MAPI protocol for incoming and outgoing mail is disabled for 64-bit JVM.Session. BMC Remedy Email Engine behavior with PLAIN Authentication mode BMC Remedy Email Engine did not work with the PLAIN authentication mode.com. type=store. Therefore.login.04 at javax. verify (or add) the following text: protocol=mapitransport. 4 Stop and re-start the Email Engine.CreatorModule.getTransport(Session.plain.bmc.emaildaemon.MAPIStore. vendor=mapi@bmc. BMC Remedy Email Engine does not support the PLAIN authentication mode.SenderModule. type=transport. you need to add the following parameters to the registry for the email engine to work: mail. but by design.mail. 2 On the first line.java:323) at com. instead.mapi.MAPITransport. it uses the LOGIN command mechanism to connect to the Microsoft Exchange Server. and the library cannot locate the correct class to use for MAPI.java:259) at java.lang. You can create this file if necessary. if Exchange Server uses PLAIN authentication.arsys.auth.bmc.doWork (CreatorModule.emaildaemon.auth.bmc.mapi.openTransport (SenderModule.arsys.bmc.disable=true 206 BMC Remedy Email Engine Guide .com.mail.properties file. auth. WARNING BMC Remedy Email Engine does not support the PLAIN authentication mode with the IMAP protocol. the email daemon goes to sleep for the configured time period (the default setting is 30 minutes).emaildaemon. Stopping and starting the AR System server If you stop AR System.imap. Chapter 6 Troubleshooting 207 . After these threads have been stopped. and this parameter is measured in minutes.auth. the email daemon will go back to sleep for the configured time period. When that time expires. During this time. You can adjust the configuration time that the email daemon monitors the AR System server by modifying the following line in the EmailDaemon. the email daemon stops all the appropriate threads until the AR System server is started again.disable=false -Dmail. restart the email daemon as soon as the AR System server starts.bat (Windows) or emaild. 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.bmc. If you set monitorInterval to 5. the email daemon waits five minutes before checking to see if the server is running. If the AR System server is running.login. the email daemon will restart all the appropriate threads and continue to run as it normally should.Monitor=monitorInterval monitorInterval is any valid integer.disable=true Using these parameters forces the Exchange Server and the email engine to disable PLAIN authentication and enable the simple LOGIN command mechanism. NOTE The name of the server is not used in this line.sh (UNIX) file: -Dmail.plain. you need to add the following parameters to the Emailstart.arsys. If you do not want to wait.imap. 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.properties file: com.Fixing common problems with the email engine If you start the email engine in the debug mode. BMC Remedy Action Request System 7. NOTE By shortening the time. These problems occur because the time zone is not adjusted between the Email Engine and the email client computer. you do not need to restart the Email Engine. users should submit requests and queries to an Email Engine computer located in the same time zone. add or modify the following line in the EmailDaemon. The email daemon usually checks for configuration changes every 30 minutes (the default setting). To avoid these problems. the email daemon will make more frequent calls to the AR System server. The email daemon notices this change based on the predefined interval. For more information. you should wait the default 30 minutes. To shorten this time. might experience the following problems: The query result might not be the same as a BMC Remedy User query result.Interval= configChangeCheckInterval Where configChangeCheckInterval represents an integer value and the parameter is measured in minutes.bmc. 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. The same process applies when you make changes to an existing user.arsys.6. see “Displaying date/time or numeric values in email notifications” on page 70. but not immediately.emaildaemon.properties file: com.04 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. If you are not making many changes to the configuration. A request might be registered with an unexpected date or time. The email daemon will notice the change. if you change the Internet email address on the form.ARSystemServerName. or manually restart the entire Email Engine system after making the configuration changes. 208 BMC Remedy Email Engine Guide . The query result might not be correct. To avoid such problems.Fixing common problems with the email engine Verifying permissions for the Windows accounts If the Email Engine will not run as a Windows service. it is returned to the mail queue. “BMC Remedy Email Engine worksheet. 5 If you are not using MAPI.” page 102. verify that it can be run manually using the following procedure. verify that the Email Engine user account has the advanced user rights and necessary permissions as described in the Installation Guide. It alerts the administrator to the types of messages being submitted incorrectly. If a message triggers a notify filter and is returned as undeliverable. items that are not valid email submissions will reside in the AR System mail server mailbox. It prevents undeliverable messages from firing duplicate notify filters. create a rule in your email program that checks the body of the message for text you require users to include in submissions. so the administrator can instruct users as to the correct procedures for formatting and submitting messages. run EmailStart. 4 If the mail process does not run.bat. NOTE If you are using MAPI. verify that the Email Engine user account has the appropriate file system permissions on the AR System directory. To verify permissions for Windows accounts 1 Open a command prompt. Chapter 6 Troubleshooting 209 . 2 Change directories to the AR System email installation directory. where it causes the filter to fire again. such as query or submit. log in to the server as the Windows account used to start the Email Engine service. or an out-of-office reply is received. set the rule to forward the email to the AR System administrator and delete it. If an incorrect email address is specified on an outgoing email notification. Troubleshooting email request processing and notify filters The Email Engine can experience problems if email submissions are not formatted correctly. NOTE If you are using an Microsoft Exchange server with SMTP and either POP3 or IMAP4. 3 At the prompt. verify that your Exchange server has the SMTP gateway enabled as well as either POP3 or IMAP4 functionality. If the message does not contain this text. This rule performs these functions: It prevents problems with the Email Engine due to improper request formatting. ” To learn how to turn on relaying. the Email Engine cleans up these temporary files. and select the check box “Allow all computers which successfully authenticate to relay. check the /var/tmp or /tmp directories. turn relaying on in your mail server. open the Relay Restrictions dialog box. check the Windows default temp directory. this is called relaying. templates. Temporary directories and files The Email Engine uses temp directories to store intermediate files for email messages. To make sure that the Email Engine can send external emails. TMP. However. Alternatively.6. see your mail server documentation. the Email Engine uses the system temp directory to manage the temporary files. you should remove these files manually.rtf Using the system temp directory By default. use the TEMP.tmp Email*. if the Email Engine terminates abnormally for some reason. then external emails will fail. or TEMPDIR environment variables to identify the system temp directory on any operation system. in Microsoft Exchange. 210 BMC Remedy Email Engine Guide . attachments.BMC Remedy Action Request System 7.html RED*. add the AR System server. Some patterns of the temporary file names that the Email Engine creates are: AT*. On UNIX.eml Email*.tmp Email*. You can locate this directory as follows: On Windows.tmp Email*. If relaying is turned off or disabled. Under normal conditions. This is a security feature to keep your server from sending thousands of unsolicited messages (or “spam”) in your company's name. For example.04 Fixing issues with notifications that fail When you send an email from the Email Engine to another domain.txt chk*.tmp E*. jar. To use an alternate temp directory On Windows.pop3.jar.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1 directoryPath is the fully qualified path where the temporary files are created. which the Email Engine does not clean up.activation.io.jar.jar.tmpdir to the emaild.arapi%LIBVER%.bmc.sh file as follows: exec ${JAVA_BIN}/java -Djava.mail.bat file as follows: "%JavaPath%\java" –Djava.imap.library.smtp.arsys.arutil%LIBVER%.tmpdir=directoryPath -Djava.path=${InstallPath} -cp ${CP_PATH} \com.jar.emaildaemon.emaildaemon.arsys. if the system temp directory does not have enough space.tmpdir to the EmailStart. Chapter 6 Troubleshooting 211 . TIP BMC recommends that you monitor these directories for files that are no longer needed.Temporary directories and files Using an alternate temp directory You can make the Email Engine point to an alternate temp directory.jar.io.bmc.armapi%LIBVER%.jar.EmailDaemon For Unix add –Djava.io.io. jar.jar com. add -Djava.tmpdir=directoryPath -cp emaildaemon. BMC Remedy Action Request System 7.04 212 BMC Remedy Email Engine Guide .6. A Appendix Setting up UNIX mailboxes You can use the following procedure to establish a mailbox address for Email Engine on the UNIX operating system. the path to your mail folder might be different from /usr/ spool/mail/. These are meant only as generic guidelines. Appendix A Setting up UNIX mailboxes 213 . 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. In particular. you must have UNIX superuser (root user) access on the UNIX server. If you have questions about implementation. it might be different for your platform. 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. you should consult your UNIX system administrator for details. To set up the AR System mailbox. To set up UNIX mailboxes 1 Set up an ARSystem user account in the /etc/passwd file. Verify this step for your UNIX operating system. as in the following example: # chgrp daemon /usr/spool/mail/ARSystem NOTE The group name varies between UNIX platforms.6. by performing the following command: # touch /usr/spool/mail/ARSystem 4 Change the group name to daemon. it is the group daemon. it is mail. For most UNIX platforms. 3 Create the mailbox file you defined for this user in the /etc/aliases file or /usr/ lib/aliases file (HP-UX). To verify the proper group name to use.1 daemon 0 May 30 16:55 /usr/spool/mail/ARSystem 214 BMC Remedy Email Engine Guide . while on HP-UX. you need to run the newaliases command to have the ARSystem aliases recognized. If you have questions or problems. check the group name for the mail directory by using the command ls -ldg. The email directory /usr/spool/mail will vary between UNIX platforms.04 NOTE On some UNIX platforms. or to the owner of the mailbox alias name. as in the following example: # chmod 666 /usr/spool/mail/ARSystem ls -laF /usr/spool/mail/ARSystem -rw-rw-rw-.BMC Remedy Action Request System 7. see your UNIX system administration documentation or UNIX system administrator. 5 Change the mailbox permissions so they are readable and writable by all. instruction template will not be overwritten by the incoming email.00 or later. Form field in the incoming mailbox Advanced Configuration tab. 6.0. Default-Schema The form to use if no form is specified in This is defined in the Default Workflow the submitted message. Default-Server Appendix B Email engine upgrade parameters 215 .1 or earlier and their equivalents (if available) in Email Engine 7. Must be specified by using a user instruction template. 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.Appendix B Email engine upgrade parameters This appendix describes the AR System configuration parameters used in the Email Engine 5.1 (or earlier) email options Address (UNIX operating system only) Function The address the mail process watches for AR System messages.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).properties file. Engine connects to that is defined in the EmailDaemon. For more information. POP3/IMAP4: Address is defined by the email server user name. see “Sending incoming email with user instructions” on page 167. Table B-1: Upgrade parameters for the Email Engine (Sheet 1 of 6) 5. The AR System server to use if no server The AR System server that the Email is specified in the submitted message. For more information. if a user submits a search request with Full Format indicated and the search matches 120 items. instruction template. full text of the original message in a reply to a failed submission.BMC Remedy Action Request System 7.6. Defines the maximum number of matches that can be returned for a successful Full Format search request. This parameter is set in the AR System Email Mailbox Configuration form in the Basic Configuration tab for MAPI Email Server Type only. MailNotifyDir (Windows only) Exchange-Profile (Windows only) Exchange-Mailbox (Windows only) Poll-Interval Query-Match-Full 216 BMC Remedy Email Engine Guide . The minimum interval is 5 seconds. Note: The value that is set in the user instruction template will not be overwritten by the incoming email. 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. Indicates the full path name for the mailntfy directory that holds all of the email notifications the server sends to the armailex service. The name given to the configuration of your Microsoft Exchange client’s operation. The armailex service deletes them after they are processed. accessible through the Control Panel mail icon). only the first 25 are returned. The Microsoft Exchange mailbox name referenced in your Exchange client’s profile configuration (found in the Microsoft Exchange Server properties. This parameter is set in the AR System Email Mailbox Configuration form in the Basic Configuration tab for each mailbox. The number of seconds to wait between polls to the mailbox to check for new messages. Valid values are T and F. full text of the original message in a reply to a successful submission.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.04 Table B-1: Upgrade parameters for the Email Engine (Sheet 2 of 6) 5. For example. Not used. Include-OriginalOn-Failure Include-OriginalOn-Success A flag indicating whether to include the Not used. see “Sending incoming email with user instructions” on page 167. Not used. A flag indicating whether to include the Not used. This field only applies to submissions. Set Reply-Failure to Discard if / dev/null does not work for your system. For Windows. Not used. For Windows. This field only applies to submissions. Appendix B Email engine upgrade parameters 217 . not searches. Not used. 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). Defines the maximum number of matches that can be returned for a successful Short Format search request. only the first 50 are returned. Use this to redirect replies for failed submissions to a third party rather than the message sender. Reply-Failure Reply-Success The email address to use for replies to successful submissions. The email address to use for replies to failed submissions.0 (or later) Email Engine equivalent Not used. To suppress replying to a successful submission. set the address to Discard. For example.Table B-1: Upgrade parameters for the Email Engine (Sheet 3 of 6) 5. Use this to redirect replies for successful submissions to a third party rather than the message sender. perform one of the following tasks: For UNIX. To suppress replying to a failed submission. set the address to Discard. perform one of the following tasks: For UNIX.1 (or earlier) email options Query-Match-Short Function 6. not searches. 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). if a user submits a search request with Short Format indicated and the search matches 120 items. If you specify a required server and a default server. A flag indicating whether to save email See “Saving outgoing notifications in items that AR System sends.” page 73.04 Table B-1: Upgrade parameters for the Email Engine (Sheet 4 of 6) 5. rejected if any other server is specified. Messages are application password or by using a security key. Do not modify this parameter. See the Installation Guide. 218 BMC Remedy Email Engine Guide . the DefaultSchema setting in the configuration file must match this form name. you must use the same server for both options.0 (or later) Email Engine equivalent The only form for which submissions are If the Force Default Workflow form is set accepted.1 (or earlier) email options Required-Schema Function 6.BMC Remedy Action Request System 7. “Upgrade of the Email Engine. In general. See the Installation Guide. “Upgrade of the Email Engine. then the Default Workflow form submitted message. Messages that do not specify a server are rejected unless the Default-Server option is defined. Only trusted email users can use this name. or the submission is rejected. Not used. The encrypted password for the Exchange account. LogoffSleep Max-Notify-MailLine-Len UseDateCheckOnFro m A flag indicating whether to check the date format when verifying new messages. If there is a Schema line in the to Yes.” page 73.6. The name of the Exchange mail server account. Windows only: Used during installation. 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. Windows only: Used during installation. Valid values for this option are Y and N. this option exists for backward compatibility only. The sender name to use for filtergenerated email notifications where no subject is specified. The name of the domain in which the Exchange account resides. form name. Do not modify this parameter. it must contain this will be the required schema. The default value is no required server. or the submission is rejected. The default value is N (do not check date format).” page 73. Windows only: Used during installation. value is F (do not save sent items). Not used. “Upgrade of the Email Engine. The only server for which email message This can be enforced by setting the requests can be submitted. Do not modify this parameter. The default configuration settings” on page 182. If there is no Schema line. This field is limited to 29 characters. Valid values MAPI” on page 44 and “Performance and for this option are T and F. See the Installation Guide. Not used. the system uses the date format specified in the Regional Settings of the user account that runs the service.properties file. see “Using label/ value pairs in templates” on page 146. Windows only: This value consists of a string of operators as defined by Regional Settings.Table B-1: Upgrade parameters for the Email Engine (Sheet 5 of 6) 5. UNIX only: This value consists of a string of operators as defined by the strftime library call. Windows only: This value consists of a string of operators as defined by Regional Settings. UNIX only: This value consists of a string of operators as defined by the strftime library call.1 (or earlier) email options Environment ARDATE Function The date and time format used by the program. (Some combinations are displayed successfully but cannot be translated for input.) If you do not set this variable. ARDATEONLY The date format used by the program. the system uses the date format specified in the Regional Settings of the user account that runs the service. 6. (Some combinations are displayed successfully but cannot be translated for input. The RPC socket that the Email Engine uses is defined in the EmailDaemon. Appendix B Email engine upgrade parameters 219 .) If you do not set this variable. ARRPC UNIX only: The specific RPC socket to communicate with during the run of the program. and the program does not run. an error is returned. the system uses the date format for the language specified by the LANG environment variable. If you do not set this variable. For information about defining an RPC socket in a template. the system uses the date format for the language specified by the LANG environment variable. Not used. If you do not set this variable. If no AR System server is running on the identified socket.0 (or later) Email Engine equivalent Not used. 1 (or earlier) email options ARTIMEONLY Function The time format used by the program. the system uses the date format specified in the Regional Settings of the user account that runs the service. 220 BMC Remedy Email Engine Guide . UNIX only: This value consists of a string of operators as defined by the strftime library call.0 (or later) Email Engine equivalent Not used.) If you do not set this variable.04 Table B-1: Upgrade parameters for the Email Engine (Sheet 6 of 6) 5. then the mail environment variable is used. the system uses the date format for the language specified by the LANG environment variable. This is set using the inbox path. If the inbox path is not set. MAIL UNIX only: The directory where email files are stored. Windows only: This value consists of a string of operators as defined by Regional Settings.6. 6. If you do not set this variable. (Some combinations are displayed successfully but cannot be translated for input.BMC Remedy Action Request System 7. The default is /usr/ mail (for the HP-UX and Oracle Solaris operating systems) or /var/spool/ mail (for the IBM® AIX® operating system). Appendix C 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.” 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 Examples of email templates 221 . “Using email templates. or you can use the examples to create your own templates. You can copy and paste these examples into the body of an email message. see Chapter 5. For more information. ) 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. b In the fields section of the email template.04 Creating email templates to search for Request ID You must use the Query Action label (or its alias) to perform a search action. It must have a field ID value of 1. however. Query Format: Short Values: Short. c Enter the Request ID of the entry to be retrieved. 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. Full Submitter !2!: Short-Description !8!: 2 Edit the exported file. define only the Request ID. Full !1!:TT00000000119 222 BMC Remedy Email Engine Guide . create the template using a text editor. (The only field in the body should be !1! requestIDNumber. The following examples use templates that have been exported using BMC Remedy Developer Studio and show how to modify them.6. a Change the Action:Submit to Action:Query. d Remove all other fields from the mail template.BMC Remedy Action Request System 7. You can. 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. AR System. b To use a format other than the default (Short). a Change the Action:Submit to Action:Query.Creating email templates to search for fields Creating email templates to search for fields To create an email template to search for a field 1 Export the email template for the form that you want to make available for searching. Low Last Name !5386753452!: Phone Number !5386748345!: 2 Edit the exported file. Query Format: Short #Values Short. NMP. An example of a mail template for a form follows. but remove all other information. The following example shows an exported template that was modified to search for multiple fields. email. set the Format option. c Edit the fields portion of the email template to include the fields you are searching. Schema: AR-HD Calls Server: polycarp Login: Password: Action: Query Format: Full Source !5368737933!: Phone Caller Impact !5368783455!: Low Appendix C Examples of email templates 223 . ACD Caller Impact !5368783455!: Low Values: High. Medium. Full Source !5368737933!: Phone #Values: Phone. # File exported Tue May 21 21:38:47 2004 Schema: AR-HD Calls Server: polycarp Login: Password: Action: Submit #Values Submit. Medium. AR System. email Caller Impact !5368783455!: Low Values: High. Schema: AR-HD Calls Server: polycarp Login: Password: Action: Query Format: Short Qualification: 'Source' = "Phone" OR 'Source' = "email" 224 BMC Remedy Email Engine Guide . Full Source !5368739331!: Phone Values: Phone. The following example shows an exported file that was modified to search using the Qualification label. Low Last Name !5386753452!: Phone Number !5386748345!: 2 Edit the exported file. a Change the Action:Submit to Action:Query.BMC Remedy Action Request System 7.6. Query Format: Short Values: Short. 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. b Remove all fields in the message and include a Qualification label.04 Creating email templates to perform searches using qualifications To create an email template to search using a qualification 1 Export the email template for the form that you want to make available for searching. Creating email templates that include attachments Creating email templates that include attachments This section contains a sample email template that includes an attachment field. Full filter. Login name. password. Attach!536880912!:). Query Format: Short # Values: Short. 6 Supply the attachment file name including the extension after the attachment field parameter. create a new email. for example. as shown here: # File exported Fri Mar 07 10:30:40 2004 Schema: Email Submit Server: polycarp Login: Password: Action: Submit # Values: Submit. 3 In a third-party client tool such as Microsoft Outlook Express. not the attachment pool. 4 Copy and paste the template into the body of the email 5 Add all the required values. 2 Edit the template to include the label and value for an attachment field (for example. A user email template filled out with a Schema: Email Submit Server: polycapr Login: Demo Password: Action: Submit # Values: Submit. 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. Make sure that the form contains an attachment pool and a valid attachment field. and so on. To create an email template that includes attachments 1 Export the email template for the form that you want to make available for submitting.log file attached appears as follows: Appendix C Examples of email templates 225 . Query Format: Short # Values: Short. Full Submitter ! 2!: $USER$ Short Description ! 8!: Need to create new post office box.ini Action: Query Qualification: 1=1 226 BMC Remedy Email Engine Guide .log attachment file anywhere in the email. 8 Send the email to the incoming mailbox. When creating or modifying templates. Creating an email content template with Submit and Query actions The following example submits an entry into a form. the email submission will fail. then queries that same form. !Last Name!: Stampovich !First Name!: Ivan !Email!: stampovic@bmc. Schema: HD Incident Server: polycarp Login: Demo Password: Action: Submit # Values: Submit. Query Format: Full # Values: Short. If the attachment name including the extension is not supplied in the email template. Attach!536880912!: filter.04 Submitter ! 2!: Demo Short Description ! 8!: Submitting email with attachment file.6. !536870920!: boot. Any value declared after the Action statement takes precedence over the global definition for that action only. the Schema and Server label/value pairs are global. any values that are defined before the Action label are global and apply to all the actions specified. and therefore apply to both the Submit and Query actions.log 7 Insert your filter. In the following example.BMC Remedy Action Request System 7.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. the Email Engine uses the default internal text format.. Appendix C Examples of email templates 227 . as in the following extract: Schema: HD Incident Server: polycarp Result: HDIN Content Login: Demo Password: . along with any other entries that meet the qualification. enter the Result Template label/value pair as a global declaration in the body of your email... 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.Creating an email reply using result templates in HTML format If you did not specify a template for the email reply. Because no template was defined as a Results Template. Creating an email reply using result templates in HTML format For the Email Engine to include a Result Template in the reply email. see “Variables” on page 156. it will use the result template shown in Figure C-2.04 When the Email Engine sends the reply email. see “Adding attachments to HTML templates” on page 162.6. For more information about results templates. For more information.BMC Remedy Action Request System 7. For more information. #$$Last Name$$#). The administrator only specifies the fields that are of interest. It formats the reply and substitutes values for the variables. see “Using HTML result templates with outgoing email” on page 93. For more information. When you send your email. The Result Template must be stored in the AR System Email Templates form before it can be used in the email. see “Storing templates in the AR System Email Templates form” on page 161. see “Result Template label” on page 151. 228 BMC Remedy Email Engine Guide . variables correspond to a field on the HD Incident form on which the template is based (for example. In this template. the Email Engine parses and executes the instructions in the Results template. the graphics must also be added using the Template Attachments tab of the AR System Email Templates form. Figure C-2: Reply to an action email using a result template For a detailed example. If graphics are included. and these are not contained in the HTML file. 0 Transitional//EN"> <HTML><HEAD><TITLE>HDIN_Content</TITLE> <META http-equiv=Content-Type content="text/html.00. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4. Figure C-3: An HTML result template The following HTML code was used to create the result template shown in Figure C-3.</TD> Appendix C Examples of email templates 229 . and then adapt what you need for your own result template. you can professionally format the reply results that users see. paste.Sample HTML result template Sample HTML result template If you create your result templates with HTML.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%"> . Copy. charset=iso8859-1"> <META content="MSHTML 6.2800. </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.BMC Remedy Action Request System 7.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 BMC Remedy Email Engine Guide .</TD> <TD width="37%"> .6.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.04 <TD width="14%"> . as in the following extract: Schema: HD Incident Server: polycarp Status Template: Status Default Login: Demo Password: .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.. For more information about status templates. The Email Engine substitutes values for the variables. Similarly. If there is an error. see “Status Template label” on page 151.. Figure C-4: A reply with the status template Appendix C Examples of email templates 231 . the Email Engine parses and executes the instructions in the content template. When you send your email.. the Status Template must be stored in the AR System Email Template form. the resulting status email will be formatted like Figure C-4. For more information. see “Header Template and Footer Template labels” on page 152.6. 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 . For more information. the templates must be stored in the AR System Email Templates form before they can be used in the email. see “Storing templates in the AR System Email Templates form” on page 161. you must also add the graphics using the Template Attachments tab of the AR System Email Templates form. 232 BMC Remedy Email Engine Guide . and these are not contained in the HTML file.04 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. Use the template fields on the AR System Email Messages form to determine the templates used when creating an outgoing message. 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..BMC Remedy Action Request System 7. If graphics are included. For more information. see “Adding attachments to HTML templates” on page 162. In each case.. The label/value pair method is used when requesting results from a server by email. They are not imported when you restart the AR System server.D Appendix Email Engine forms The Email Engine provides a set of administration. you must import those forms manually. 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 . WARNING BMC recommends that you do not archive or audit the forms containing core fields. user. NOTE If any of the email forms are deleted after you install the Email Engine. These forms are generated when you install the Email Engine. and workflow forms for configuring and processing email from your mail server. BMC Remedy Action Request System 7.6. If you use different naming conventions in these forms. For more information. 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 similar naming conventions for both the AR System Email Configuration form and the AR System Email Failover Mail Server form. but the failover mail server is not used successfully if the primary mail server stops working. 234 BMC Remedy Email Engine Guide . an error message is displayed and you are not allowed to save the form. see “Multiple mail server support” on page 24. The name or IP address of the mail server that acts as a failover system for the other mail server mentioned on this form. If you use the server name in one field and the IP address in the other. you can also specify a failover server for each failover server. However. You should use either the server name or the IP address in both fields. 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 results are displayed as shown in Figure D-1 on page 235. You should not provide the IP address in one form and the server name in the other.04 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. no error is displayed. When you search for failover mail servers using the AR System Email Failover Mail Server Configuration form. Mailbox Function Select whether mailbox is Incoming or Outgoing. see “Configuring outgoing mailboxes” on page 28 and “Configuring incoming mailboxes” on page 32. For each mailbox. connection and security provisions. For more information. actions associated with the mailbox. Incoming mailbox—Basic and Advanced Configuration tabs Table D-2: AR System Email Mailbox Configuration—Basic 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. the form provides a name and email address for the mailbox administrator. and defaults.Email Engine administration forms 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. Appendix D Email Engine forms 235 . Select Disabled to keep the mailbox disabled. Email Server Password Profile Name Associated Mailbox Name Email Action Enter the user name of the administrator or user for this email account. If you do not enter a port number. or accept the default value of None for no action. Select Parse to enable the Email Engine to detect and process instructions included in an incoming email message. Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (BMC Remedy Mail Server release 5. Used only with POP3 and IMAP4. Email Server Port Enter the port used for connecting to the mail server. 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 POP3 and IMAP4. Enter the name of an outgoing mailbox used to reply to incoming emails that require a response. Enables the secure socket layer. Enter the name or IP address of the mail server used in your organization. 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. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Use Original Template Format 236 BMC Remedy Email Engine Guide .BMC Remedy Action Request System 7. Enter the name of the Microsoft Exchange profile to be used for incoming mailbox. 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.6. Used only with MBOX. Used only with POP3 and IMAP4.04 Table D-2: AR System Email Mailbox Configuration—Basic and Advanced (Sheet 2 of 3) Field name Description Email Server Type Select the email protocol. Used only with MAPI.1 or earlier) and thus ignore special HTML fields and XML formats. 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. Appendix D Email Engine forms 237 . Enable Modify Actions Select Yes to enable modify actions. 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. Select Disabled to keep the mailbox disabled. 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. Reply With Entry Select Yes to return the complete entry of a submit or modify action. 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. Outgoing mailbox—Basic 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. This action will confine all instructions received by this mailbox to the specified form. Basic Configuration tab Email Server Type Select the email protocol. 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.Email Engine administration forms Table D-2: AR System Email Mailbox Configuration—Basic 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. Select No to use the default single-line entry. Mailbox Function Select whether mailbox is Incoming or Outgoing. or No to prevent modify actions from being performed. Select Enabled to activate the mailbox. make sure that the character case of the email address from the user form and email address of the sender is the same. or select No if results should not be included. Email Server Port Enter the port used for connecting to the mail server. if you plan to enable users to reply to notification messages sent from this mailbox. Enter the name of the incoming mailbox that will be used to receive instructions or notifications. 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. Enter the default email addresses for those who should receive copies of outgoing messages from this mailbox. Display Name Email Address Enter the name you want displayed in the From line of the outgoing email. 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. Used only with MAPI. or administrator’s organization. Used only with SMTP. Enter the email addresses to send to if addresses have not been specified in the Messages tab for a notify filter or escalation. Used only with SMTP. Enter the name of the Microsoft Exchange profile to be used for the outgoing mailbox. 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 name of the mailbox owner. If you do not enter a port number. Organization Delete Outgoing Notification Messages Default Addressing Default To Default CC Default BCC For email clients that display an organization name. 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.6. 238 BMC Remedy Email Engine Guide . Used only with SMTP.04 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. Reply To Address Enter the Reply-to email address for the mailbox owner or administrator. Enter the name or IP address of the mail server used in your organization. Enter the default email addresses for those who should receive outgoing messages from this mailbox.BMC Remedy Action Request System 7. Enter the default email addresses for those who should receive blind copies of outgoing messages from this mailbox. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Enter the full email address of the administrator or owner of this mailbox. the language encoding used. then click inside the field. HTML file or bitmap) that is always used with a specific template. Appendix D Email Engine forms 239 . the format used and a name and description for the template. You must store templates in the AR System Email Templates form before you can use them. either Text or HTML. and information about attachments associated with this template. the default encoding of the local system is employed. Lets you select and add an attachment (for example. Enter the name of the email template. 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. when you add an email template to a Notify action. For more information. You can edit the name as needed.Email Engine administration forms 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. the AR System Email Templates form uses data-driven workflow to populate menus in the Email Engine forms that use templates. For each template. and modify templates applied to email messages. Includes size and label information. Choose the language setting used to read and parse the contents of templates. You can use this form to create standard templates that users can access for creating specific types of messages. AR System Email Templates form Use the AR System Email Templates form to create. for example. you can add these as attachments to the template in the AR System Email Templates form. After saving your template. Template Name Add Attachment button Click to open the AR System Email Attachments form in New (HTML templates only) mode. To include graphic elements in your email. then this template will be used by default. see “Storing templates in the AR System Email Templates form” on page 161. display. Description File Name (Optional) Select the template files from the Attachment field. 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. The contents of the Template Name field are automatically populated if you attach a new file. Enter the template to be used as the default status template. If no setting is specified. Enter the template to be used as the default result template. this form provides: the unique template ID. For each instruction template. start and stop times for the Email Engine. AR System Email User Instruction Templates form Use the AR System Email User Instruction Templates form to store administratordefined instructions for specific actions. and the instructions themselves. Template Name Menu lets you select template that is executed as the content of user instruction and used in the email. and configuration changes. message number. For more information. and the text of the error message. The contents of this field are read-only. Mailbox Name Instruction Menu lets you associate incoming mailbox used with user instruction. the form provides the template name. Click to delete the attachment from AR System Email Attachments form. the message type. name of the mailbox with which the instructions are associated. The template will not (HTML templates only) be available for use until the Email Engine cache is updated. or (HTML templates only) deleted an attachment. log connection status information for email servers and the AR System server.6. modified. 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. Valid character string consisting of Action label and value used to access user instruction field. Description Click to open the AR System Email Attachments form in Search mode so you can modify an attachment. These instructions can include variables whose values are provided when the instructions are executed.BMC Remedy Action Request System 7.04 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. see “Sending incoming email with user instructions” on page 167. as well as all incoming and outgoing mail messages. and to associate those instructions with a template defined in the AR System Email Templates form. how the error message was generated. 240 BMC Remedy Email Engine Guide . Table D-5: Fields on the AR System Email User Instruction Templates form Field name Instruction Template ID Description System-generated unique ID. Each log entry includes the ID for the mailbox and the message. Adds an existing attachment to the template. You can use almost any combination of letters and numbers for a security key.Email Engine administration forms For more information. Info: Status information. and Create Date Mailbox ID Number Message Type Number of the message to which the log applies. Fine: Internal exceptions. Menu that lets you activate the key. Select Disabled to keep the key disabled. which are handled by the application but logged for tracing purposes. This is the default value. For more information. see “Configuring outgoing mailboxes” on page 28 and “Configuring incoming mailboxes” on page 32. Either an error log or a status log—and the severity level of the message. or to all incoming mailboxes. A security key can be assigned to an individual incoming mailbox. For configuration information. Message Number Generated By Message Text Error number associated with the message. 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. 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. Config: Information related to mailbox configuration. Error generated either by the Email Engine or by the AR System server. see “Configuring incoming mailbox security” on page 39. Force for Mailbox Enables the security key for this mailbox only. Name of a valid AR System user to whom the security key should apply. Name of key consisting of a set of alphanumeric characters. Finer: Trace logs that record specific tasks as they are executed within the application. Severity levels are as follows: Severe: Errors that prevent successful execution of a specific task and might require administrator intervention. The contents of this field are read-only. Appendix D Email Engine forms 241 . Description of the error. Select No to enable the key for all mailboxes in your email environment. Warning: Errors that can cause problems when executing a task. AR System Email Security form Use the AR System Email Security form to either create and enable or disable security keys for incoming mail. and (under a separate tab) a list of any attachments included with the message.” 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.BMC Remedy Action Request System 7. If you select Yes. you can either modify the expiration date in this form. Option that verifies incoming messages from a set of specific email accounts using a security key. Description for the key. or set the Expires field to No. For information about using the Email Messages form to troubleshoot traffic between incoming and outgoing email. Select Yes to display the advanced options available for viewing email information and errors. such as why it was created or instructions for modifying or deleting it. Key required for mail received from specific email accounts. Each message is stored as an entry in the AR System Email Messages form. 242 BMC Remedy Email Engine Guide . this form provides the name of the mailbox from which the message was generated.04 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. name and organization of the mailbox owner. “Outgoing email. names of recipients sent to and copied. or a combination of both). Select whether mailbox is Incoming or Outgoing. Expiration date for this security key. For each message. 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. see Chapter 3. plain text format. the message type. the Email Address field becomes enabled. the text of the message (in HTML. After the key expires.6. or deleted an attachment. Template to be used as the footer template. Variable Replacement tab Description Appendix D Email Engine forms 243 . Removes attachment from outgoing email. Value to use in the email message to get the desired Microsoft Outlook priority. Subject line for your email. Reply-to email address for the mailbox owner or administrator. Value for a variable in the template. Advanced Options tab Table D-11: Fields on the AR System Email Messages form—Advanced Options tab (Sheet 1 of 2) Field name Templates tab Header Template Footer Template Field Values Template to be used as the header template. Email addresses for those who should receive blind copies of outgoing messages from this mailbox. or administrator’s organization. Email addresses for those who should receive outgoing messages from this mailbox. Lets you modify attachment or attachment name. For email clients that display an organization name. the name of the mailbox owner. Refreshes table after you have added. Email addresses for those who should receive copies of outgoing messages from this mailbox. modified. if you plan to enable users to reply to notification messages sent from this mailbox. Numbers from 1 to 100 are acceptable. Includes previously saved attachment with outgoing email.Email Engine user forms Message tab Table D-9: Fields on the AR System Email Messages form—Messages tab Field name From: Reply To: Description Name of the mailbox the email is sent from. Organization: To: CC: BCC: Subject: Priority: Attachments tab Table D-10: Fields on the AR System Email Messages form—Attachments tab Field name Add Attachment Modify Attachment Delete Attachment Refresh Table Add Existing Description Includes attachment with outgoing email. Content Template Template to be used as the content template. BMC Remedy Action Request System 7. or RTF attachment. Language encoding used. name of the server on which the form resides. HTML. Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding Language encoding used. The date on which the message was sent. 244 BMC Remedy Email Engine Guide . Attachment Alternatives tab Attachment Attachment pool enables you to add the content of your email as a Alternatives plain text.6. The timestamp of when the incoming message was executed. Message Information tab Table D-12: Fields on the AR System Email Messages form—Message 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.04 Table D-11: Fields on the AR System Email Messages form—Advanced Options tab (Sheet 2 of 2) Field name Description AR System Server With qualification variables. AR System Server With qualification variables. instead of typing it into the (attachment pool) Body field in the Message tab. Query used to retrieve data and substitute it in the email. RPC Number AR System Form Qualification With qualification variables. any access information necessary. this value is retrieved from the Date header of the incoming message. applicable to outgoing messages only. Language encoding used. The date on which the message was sent. Plain Text Content Language encoding used. name of the AR System form to which these values apply. TCP Port AR System Server With qualification variables. or when the outgoing message was sent. any access information necessary. Sent—The message was successfully sent. Send Message The sending status of the message. because an error occurred at the previous attempt. Error Sending-Retrying—The Email Engine is trying to send the message again. AR System Email Error Messages form In the BMC Remedy AR System 7. is stored in this form with the error details. Any incoming email message that has not been processed correctly due to any runtime error. Errors tab Enables users to view error messages if their email is not sent correctly. Appendix D Email Engine forms 245 . The options and their meanings are: No—The message has not yet been sent. Log Message Text If a request fails to submit. Parsed & Executed—The message was successfully parsed and executed. the error message that indicates the reason for the failure is returned.02 release. you can copy these incoming messages to the AR System Email Messages form. Error—An error occurred when parsing the message. applicable to outgoing messages only. NOTE This form stores information only for incoming email messages. Error—An error occurred when sending the message.Email Engine user forms Table D-12: Fields on the AR System Email Messages form—Message Information tab (Sheet 2 of 2) Field name Parse Message Description The parsing status of the message. Yes—The message is still in the outgoing queue. applicable to incoming messages only. Log Message Number Create Date The error message number. Table D-13: Fields on the AR System Email Messages form—Errors tab Field name Description Log Message Type If a request fails to submit.6. Yes—The message is still in the incoming queue. The creation date of the error message. The options and their meanings are: No—The message has not yet been parsed. the original message is returned as an attachment. After manually rectifying the errors. a new AR System Email Error Messages form has been introduced. 04 NOTE BMC recommends that you perform the rectification process individually on every error out email message. To enable the “Clean AR System Email Error Messages” escalation 1 Go to Escalation -> Execution Options. But. if there are messages in the incoming queue.6. For the Email Engine to consider the plain text format. 3 (Optional) Change the Escalation period as per your requirements from the default value of 15 days. The administrator can configure the period and the conditions for deleting these mails using the “Clean AR System Email Error Messages” escalation. All the messages in the AR System Email Error Messages form will be deleted depending upon the conditions set in the escalation. the Email Engine processes the incoming actions at the next polling interval. considers the plain text format. the Email Engine only considers the HTML format. if you want to parse the rectified messages in spite of the messages in the incoming queue. the rectified messages are parsed at the next polling interval. If the incoming message is in a plain text format. Increase the time of the polling interval. 2 Change the value of the State field to ‘Enabled’ using the drop-down menu. by default. NOTE This escalation is disabled by default. 2 Click on the “Copy to AR System Email Messages Form” button. change the status of the message to “Yes”. are not deleted even after they are moved to the AR System Email Messages form. 246 BMC Remedy Email Engine Guide . NOTE Additional conditions can be set using the Run Process field. The messages stored on the AR System Email Error Messages form. Do not perform the rectification process on more than one email message at the same time using the ‘Modify All’ option. change the HTML format to a plain text format (without any spaces) or clear the HTML format. After the rectified messages are copied to the AR System Email Messages form.BMC Remedy Action Request System 7. WARNING (For incoming mails that have not been processed correctly due to any runtime error) The Email Engine considers the HTML format. To copy the rectified incoming messages to the AR System Email Messages form 1 From the Message Information tab. However. Email Engine first checks for the HTML format and when not found. if the incoming mail is in a plain text as well as HTML format. Numbers from 1 to 100 are acceptable. or deleted an attachment. plain text format. Appendix D Email Engine forms 247 . or a combination of both). 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. Lets you modify attachment or attachment name. Select whether mailbox is Incoming or Outgoing. this form provides the name of the mailbox from which the message was generated. Email addresses for those who should receive blind copies of outgoing messages from this mailbox. Subject line for your email. and (under a separate tab) a list of any attachments included with the message. name and organization of the mailbox owner. the name of the mailbox owner. Organization: To: CC: BCC: Subject: Priority: Attachments tab Table D-16: Fields on the AR System Email Error Messages form—Attachments tab Field name Add Attachment Modify Attachment Delete Attachment Refresh Table Add Existing Description Includes attachment with outgoing email. Includes previously saved attachment with outgoing email. Email addresses for those who should receive outgoing messages from this mailbox. For email clients that display an organization name. the text of the message (in HTML. modified. names of recipients sent to and copied. the message type. Removes attachment from outgoing email. Email addresses for those who should receive copies of outgoing messages from this mailbox. Table D-14: Fields on the AR System Email Error Messages form Field name Mailbox Name Mailbox Type Description Name of configured mailbox. Value to use in the email message to get the desired Microsoft Outlook priority. Refreshes table after you have added. Message tab Table D-15: Fields on the AR System Email Error Messages form—Messages tab Field name From: Reply To: Description Name of the mailbox the email is sent from. or administrator’s organization.Email Engine user forms For each message. or RTF attachment. name of the AR System form to which these values apply. TCP Port AR System Server With qualification variables. Query used to retrieve data and substitute it in the email. Content Template Template to be used as the content template.04 Advanced Options tab Table D-17: Fields on the AR System Email Error Messages form—Advanced Options tab Field name Templates tab Header Template Footer Template Field Values Template to be used as the header template. any access information necessary. AR System Server With qualification variables.6. Plain Text Content Language encoding used. instead of typing it into the (attachment pool) Body field in the Message tab. Language encoding used. name of the server on which the form resides. this value is retrieved from the Date header of the incoming message. RPC Number AR System Form Qualification With qualification variables. Template to be used as the footer template. Language encoding used. any access information necessary. Message Information tab Table D-18: Fields on the AR System Email Error Messages form—Message Information tab (Sheet 1 of 2) Field name Message ID Date Received Description The unique value that identifies the message. 248 BMC Remedy Email Engine Guide . Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding Language encoding used. HTML. Description Attachment Alternatives tab Attachment Attachment pool enables you to add the content of your email as a Alternatives plain text. The date on which the message was sent.BMC Remedy Action Request System 7. Value for a variable in the template. Variable Replacement tab AR System Server With qualification variables. or when the outgoing message was sent. Parsed & Executed—The message was successfully parsed and executed. the error message that indicates the reason for the failure is returned. the file name. The timestamp of when the incoming message was executed.Email Engine user forms Table D-18: Fields on the AR System Email Error Messages form—Message Information tab (Sheet 2 of 2) Field name Date Sent Execute/Send At Parse Message Description The date on which the message was sent. AR System Email Attachments form Use the AR System Email Attachments form to create. Error—An error occurred when parsing the message. the original message is returned as an attachment. a text file). Yes—The message is still in the incoming queue. Log Message Number Create Date The error message number. Log Message Text If a request fails to submit. applicable to incoming messages only. For each attachment. whether the attachment is an email attachment or a template attachment. Errors tab Enables users to view error messages if their email is not sent correctly. display. size. and label. the type of attachment (for example. applicable to outgoing messages only. The creation date of the error message. Table D-19: Fields on the AR System Email Error Messages form—Errors tab Field name Description Log Message Type If a request fails to submit. including incoming email. and modify information about attachments used with emails and templates. The options and their meanings are: No—The message has not yet been parsed. Appendix D Email Engine forms 249 . The parsing status of the message. the name of the attachment. the form provides a unique ID. Users can access attachments from this form when they compose an email message.6. Email Engine workflow forms This section describes the workflow forms available with the Email Engine. you should not create or modify entries in this form. It also stores attachments for templates. Table D-20: Fields on the AR System Email Attachments form Field name Type Description Email or Template attachment. 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.04 Administrators can access this form from the Template form if an attachment is needed for a new template. Attachment Name Name of attachment. 250 BMC Remedy Email Engine Guide . AR System Email Attachment Join form The Email Engine uses the AR System Email Attachment Join form for mapping attachments to email messages. Used for storing attachments for both incoming and outgoing emails. you should not create or modify entries in this form.BMC Remedy Action Request System 7. WARNING Because this information is used internally by the Email Engine. such as a graphic for an HTML template. WARNING Because this information is used internally by the Email Engine. File Name Enables users to view error messages if their email was not sent (attachment pool) correctly. For incoming messages. For outgoing messages. this information includes associations for attachments that should be included when the message is sent. you should not create or modify entries in this form. Destination ID (the ID of the attachment). the form reflects the association between a template and any attachments that should be included when that template is used. or between a template and one or more attachments. An example is an HTML template with graphics that must be included to make sure that the message is displayed correctly.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. This association enables multiple emails to be associated with one attachment. Destination type (email attachment). the form provides: Unique ID. If the source type is template. Source ID (the ID of the email or template). Appendix D Email Engine forms 251 . 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. WARNING Because the information in this form is used internally by the Email Engine to store instructions. this information includes the association between the message and any attachments included with the message. or one email to be associated with multiple attachments. Source type (email or template). you should not create or modify entries in this form. WARNING Because this information is used internally by the Email Engine. For each association. 04 252 BMC Remedy Email Engine Guide .6.BMC Remedy Action Request System 7. 148 A accounts email 17 permissions for Windows 209 Action label 146. adding to outgoing mail 91 Basic tab incoming mailbox 235 outgoing mailbox 237 Index 253 . 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. 74.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. 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. 226 Submit 113. 20 Attachment Alternatives tab fields 244. 237 Advanced Options tab fields 243. 235 outgoing mailbox 30. email engine 18. 247 audience for this guide 11 Authentication label 146. 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. 149 Notify 56. 242 AR System Email Security form 241 AR System Email Templates form 161. 248 incoming mail 136 outgoing mail 82 API errors 176 appearance. 152 !Name! label 147. 152 AR System Email Instructions form 250 AR System Email Mailbox Configuration form 235 AR System Email Messages form 54. 61. 226 administrator-defined instructions storing 240 storing parameters 251 Advanced Configuration tab incoming mailbox 33. 149 actions Modify 42. 149. 128 Query 149. 243. See mail EmailDaemon. contacting 2 body.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. See messages Email Security form 241 Email Templates form 239 Email User Instruction Templates form 240 email. creating email debug 192 BMC Remedy Email Engine. 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. AR System 11 dynamically assigning templates to outgoing mail 66 C character sets incoming mail 138 outgoing mail 88 checkbox buttons. global and local parameter 156 default outgoing mailbox 28 deleting attachments in outgoing mail 81 notifications 70 template attachments 165 documentation.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 batch files. 245 email messages. 178 Main Application Level option 178 Module Levels option 178 254 BMC Remedy Email Engine Guide . including incoming in outgoing mail 101 buttons HTML checkbox 155 HTML radio 155 options for email engine 177 declarations. 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. See email engine BMC Software. 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. 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. 242. 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. 178 Header Template label 146. 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. 152 footer templates about 141 adding 232 Form label 146.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 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. 150 using 112. 245 AR System Email Security form 241 AR System Email Templates 161. 147 . 152 header templates about 141 adding 232 using as banners 91 heap. 144 templates with attachments 166 Format label about 146. 74. 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. 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. 150 Header Template 146. See IMAP4 protocol intervals. 152 !Name! 147.properties file 88 K Key label 147. logging 176 256 BMC Remedy Email Engine Guide . 148 Footer Template 146. 148 Login 146. 151 TCP Port 146. 115. 152 Key 147. 146. 149 Authentication 146. 153 Language 146. 147 Status Template 146. 147 Password 146.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 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. 127 security configuration form 241 keywords labels and 140. 170 storing administrator-defined 240 storing administrator-defined parameters 251 Submit 113 user templates 143 user variables 172 Internet Message Access Protocol. 147 Qualification 146. 170 status information 137 storing 242. 151 Query Action 222 Request ID 147. 147 using in templates 146 Language label 146. changing form entry retrieval 44 J JavaToMimeMapping. 147 Format 112. 153 Result Template 146. 199 INFO logging level 177 instructions about 18 about user 150. 148 levels. 151 RPC Number 146 RPC Port 148 Server 146. 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 about 140 Action 146. 152 Form 146. 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. 153 keys creating security 39. 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. 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. 247 messages See also error messages defining in notifications 61 mapping attachments to 250 Messages tab 61 Messaging Application Programming Interface protocol. 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. 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.properties file 17 SEVERE level 176 system status 174 transmission failures 176 Logging module 19 logging.properties file 17. 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 mailboxes about 18. 248 incoming mail 137 outgoing mail 87 Message tab 243.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 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. HTML 155 Message Information tab fields 244. 147 menu fields. 177 Login label 146. 147 passwords identifying invalid application service 203 permissions. 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. 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. global and local 156 Password label 146. 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. 97 HTML result templates 93 improving appearance 22. 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 . 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. 245 templates 71. verifying Windows account 209 plain text sending modify instructions 119 sending outgoing mail in 75 POP3 protocol 16 Post Office Protocol.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 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. 199 P parameter declarations. See SSL security configuration form 241 configuring email 38 creating keys 39. outgoing mail 79 Basic Configuration. 249 Errors. incoming mail 136 Advanced Options. fields 244. 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. mail servers identifying AR System for email engine 179 SEVERE logging level 176 shorthand qualification syntax 111 Simple Mail Transfer Protocol. replying with 41 RPC Number label 146. 147 servers See also failover mail servers. 248 Attachment Alternatives. See SMTP protocol SMTP protocol about 16 custom headers for outgoing mail 89 SSL. 151 result templates about 142 creating HTML for mail reply 227 using HTML with outgoing mail 93 using XML with outgoing mail 96 results. incoming mail 137 Index 259 . 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. outgoing mailbox 30. troubleshooting email engine 202 status HTML template 231 incoming mail 137 outgoing mail 87 system logs 174 Status Template label 146. outgoing mail 82 Attachment Alternatives. incoming mailbox 33. 237 Advanced Options. 148 S searching for entries to modify 132 entries with qualifications 224 fields with templates 223 request IDs with templates 222 Secure Sockets Layer. 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. fields 243. HTML 155 Receiver module 19 receiving mail 16 replies. 153 request IDs. outgoing mailbox 237 Errors. 235 Advanced Configuration. incoming mail 136 Attachment Alternatives. incoming mailbox 32 Basic.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 R radio buttons. outgoing mail 86 Attachments. configuring for email engine 45 startup. incoming mailbox 235 Basic. customer 3 syntax label/value pair 153 shorthand qualification 111 system status logs 174 T tabs Advanced Configuration. 248 Advanced Options. 245 templates 161 Submit action about 149 creating content template with 226 sending instruction to email engine 113 support. 247 Attachments. 151 status templates about 142 outgoing mail 99 storing email messages 242. fields 243. fields 245. 156 XML outgoing content 73 XML outgoing result 96 Templates tab on Advanced Options tab 82. 248 TCP Port label 146. email engine 17 testing incoming mailbox 199 mail 129 mailbox configurations 36 outgoing mailbox 199 text fields. 243. 167 value/label pairs and 146 variables and 135.properties file 179 instruction failures 176 logging email engine problems 200 logs 174 mail servers 205 mailbox configuration 36. 248 Templates on notify filter 61. 248 Message Information. 144 exporting with attachments 166 footer 141 header 141 header as banner 91 HTML outgoing content 73. fields 244. incoming mail 137 Message Information. 248 Templates tab on notify filter 61. 243. HTML 155 time zones. 198. 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. 247 Message Information. outgoing mail 87 Fields 59 Message 243. 64 terminology. outgoing mail 87 Messages 61 Template Attachments 163 Templates on Advanced Options tab 82. 243. 64 Variable Replacement 83. 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.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 Errors. 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. 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. 167 creating 169 creating templates for 168 260 BMC Remedy Email Engine Guide . 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. incoming mail 137 error messages. 243. 170 templates 143 variables 172 V Variable Replacement tab 83. 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 . 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.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 results 171 sending in incoming mail 167. 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 262 BMC Remedy Email Engine Guide . . *969381* *969381* *969381* *969381* *183969* .