BMC Remedy Action Request System 7.0 Administering BMC Remedy Engine

Transcription

1 BMC Remedy Action Request System 7.0 Administering BMC Remedy Engine May 2006 Part No: 58475

2 Copyright 2006 BMC Software, Inc. All rights reserved. BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and all other BMC Software product or service names, are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software, Inc., considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable end user license agreement or nondisclosure agreement for the product and the proprietary and restricted rights notices included in this documentation. For license information about the OpenSource files used in the licensed program, please read OpenSourceLicenses.pdf. This file is in the \Doc folder of the distribution CD-ROM and in the documentation download portion of the product download page. Restricted Rights Legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section , DFARS , DFARS , DFARS , and DFARS , as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX , USA. Any contract notices should be sent to this address. Contacting Us If you need technical support for this product, contact Customer Support by at If you have comments or suggestions about this documentation, contact Information Development by at This edition applies to version 7.0 of the licensed program. BMC Software, Inc.

3 Contents Preface Audience AR System documents Learn about the AR System Developer Community Why should you participate in the Developer Community? How do you access the Developer Community? Chapter 1 Overview of the BMC Remedy Engine About the BMC Remedy Engine engine terminology Overview How the engine works Overview Improving the appearance of your Chapter 2 BMC Remedy Engine installation and setup Preinstallation steps Entering information into the installation worksheet Reviewing documentation Installing components Windows Preinstallation tasks UNIX Preinstallation tasks Windows Installing the engine Loading the software Installing the engine Contents 3

4 BMC Remedy Action Request System 7.0 UNIX Installing the engine Loading the software Installing the engine Postinstallation steps Starting and stopping the engine Chapter 3 Configuring mailboxes in the BMC Remedy Engine Overview configuration 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 Testing your outgoing mailbox Testing your incoming mailbox Configuring security Configuring incoming mailbox security Configuring outgoing mailbox security Configuring the engine for replying with results Configuring the engine for modify actions MAPI Saving outgoing notifications Changing the form entry interval time Configuring SSL for the engine Chapter 4 Outgoing Overview How outgoing works Using outgoing Using notifications Defining workflow to send notifications Dynamically assigning templates to outgoing Displaying date/time or numeric values in notifications Deleting notifications Using templates with outgoing Contents

5 Administering BMC Remedy Engine Using the Messages form to send outgoing Sending outgoing in plain text Sending outgoing in HTML Including attachments with outgoing Displaying advanced options for outgoing Determining message content of outgoing Sending reply Giving a professional look to outgoing Using header templates as a banner with outgoing Using HTML result templates with outgoing Using XML result templates with outgoing Using HTML content templates with outgoing Using status templates with outgoing Chapter 5 Incoming Overview How incoming works Using incoming Sending a query instruction to the engine Including qualifications in your Using shorthand qualification syntax Using the Format label Sending a submit instruction to the engine Using keywords Using the Format label Including attachments with incoming Sending a modify instruction to the engine Overview How modify instructions work with incoming Sending modify instructions in plain text Sending modify instructions in HTML Additional restrictions Overview Using workflow to modify requests Searching for an entry to modify Advanced solution Using variables with templates Displaying advanced options for incoming Message Information tab Errors tab Contents 5

6 BMC Remedy Action Request System 7.0 Chapter 6 Using templates Overview templates Types of templates Creating templates Exporting mail templates Using label/value pairs in templates Form label Server label Login, Password, and TCP Port labels RPC Number and Authentication labels Language label Action label Format label Qualification label Result Template label Status Template label Header Template and Footer Template labels !Name! or!id! labels Key label Request ID label Label/value pair formats Global and local parameter declarations Variables Additional tips when creating or modifying templates Storing templates in the AR System Templates form Adding attachments to HTML templates Adding a previously saved attachment to your template Modifying an attachment Deleting an attachment Exporting templates with attachments to another server Preparing templates after an upgrade Overview Sending incoming with user instructions Creating and storing a template for use with user instructions Creating user instructions Sending a user instruction in an incoming Contents

7 Administering BMC Remedy Engine Results of the user instruction Using variables with user instructions Chapter 7 Troubleshooting Troubleshooting outgoing engine architecture Error and system status logs transmission or instruction failures AR System API errors Internal engine errors Debugging options for the BMC Remedy Engine Using the Daemon.properties file Updating the Daemon.properties file Performance and configuration settings Creating debug batch files Windows Debugging the engine UNIX Debugging the engine Fixing common problems with the engine Configuring mailboxes Logging problems with the engine Defining a heap size for the engine Troubleshooting startup issues Determining problems with the mail server Stopping and starting the AR System server Making changes to mailbox configuration Submitting requests across different time zones Verifying permissions for the Windows accounts Troubleshooting request processing and notify filters Appendix A Examples of templates Creating templates to search for Request ID Creating templates to search for fields Creating templates to perform searches using qualifications Creating templates that include attachments Creating an content template with Submit and Query actions Contents 7

8 BMC Remedy Action Request System 7.0 Creating an reply using result templates in HTML format Sample HTML result template status template in HTML format Adding a header template and a footer template Appendix B engine installation worksheets UNIX Installation and configuration worksheets UNIX Installation worksheet UNIX Configuration worksheet Windows Installation and configuration worksheets Windows Installation worksheet Windows Configuration worksheet Appendix C Setting up UNIX mailboxes Appendix D Upgrading option parameters engine update parameters Appendix E BMC Remedy Engine forms engine administration forms AR System Mailbox Configuration AR System Templates form AR System User Instruction Templates form AR System Error Logs form AR System Security engine user forms AR System Messages form AR System Attachments form AR System Attachment Join form engine workflow forms AR System Instructions form AR System Instruction Parameters form AR System Association form Index Contents

9 Preface Important: The compatibility information listed in the product documentation is subject to change. See the compatibility matrix at /supportweb.remedy.com for the latest, most complete information about what is officially supported. Carefully read the system requirements for your particular operating system, especially the necessary patch requirements. Audience This guide is for administrators who are responsible for installing and maintaining the BMC Remedy Engine ( engine). Before you explore the topics in this guide, you must know how to use the BMC Remedy Action Request System (AR System ), including BMC Remedy Administrator, BMC Remedy User, and BMC Remedy Import. See the Installing guide, the Form and Application Objects guide, and the Workflow Objects guide for additional information. Your knowledge of basic administrative AR System tasks is crucial for the successful implementation of the strategies discussed in this guide. In addition, make sure that you understand the terms and concepts discussed in the Optimizing and Troubleshooting guide, which contains all the required information for setting up and administering a basic AR System environment. Preface 9

10 BMC Remedy Action Request System 7.0 AR System documents The following table lists documentation available for AR System products. Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available on AR System product installation CDs, on the Customer Support site (supportweb.remedy.com), or both. You can access product Help through each product s Help menu or by clicking on Help links. Title Description Audience Concepts Overview of AR System architecture and features with in-depth examples; includes information about other AR System products as well as a comprehensive glossary for the entire AR System documentation set. Everyone Installing Procedures for installing AR System. Administrators Getting Started Introduces topics that are usually only learned when first starting to use the system, including logging in, searching for objects, and so on. Everyone Form and Application Objects Describes components necessary to build applications in AR System, including applications, fields, forms, and views. Developers Workflow Objects Contains all of the workflow information. Developers Configuring Contains information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Administrators Installing and Administering BMC Remedy Mid Tier Integrating with Plug-ins and Third-Party Products Optimizing and Troubleshooting Contains information about the mid tier, including mid tier installation and configuration, and web server configuration. Discusses integrating AR System with external systems using plug-ins and other products, including LDAP, OLE, and ARDBC. Server administration topics and technical essays related to monitoring and maintaining AR System for the purpose of optimizing performance and troubleshooting problems. Administrators Administrators /Developers Administrators 10 Preface

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

12 BMC Remedy Action Request System 7.0 Learn about the AR System Developer Community If you are interested in learning more about AR System, looking for an opportunity to collaborate with fellow AR System developers, and searching for additional resources that can benefit your AR System solution, then this online global community sponsored by BMC Remedy is for you. In the Developer Community, you will find collaboration tools, product information, resource links, user group information, and be able to provide BMC Remedy with feedback. The Developer Community offers the following tools and information: Community message board Community Downloads AR System Tips & Tricks Community recommended resources Product information User Experience Design tips Why should you participate in the Developer Community? You can benefit from participating in the Developer Community for the following reasons: The community is a direct result of AR System developer feedback. BMC Remedy provides unsupported applications and utilities by way of Community Downloads, an AR System application. BMC Remedy posts the latest AR System product information in the Developer Community to keep you up to date. It is an opportunity to directly impact product direction through online and surveys. It s free! How do you access the Developer Community? Go to supportweb.remedy.com, and click the Developer Community link. 12 Preface

13 Chapter 1 Overview of the BMC Remedy Engine This chapter provides an overview of the BMC Remedy Engine. The following topics are provided: About the BMC Remedy Engine (page 14) engine terminology (page 16) Overview How the engine works (page 18) Overview Improving the appearance of your (page 21) Overview of the BMC Remedy Engine 13

14 BMC Remedy Action Request System 7.0 About the BMC Remedy Engine The BMC Remedy Engine is a service that transforms into an interface that communicates with the AR System server. It is included as part of the AR System and does not require an additional license. The engine enables users to instruct the AR System server to perform queries, submissions, or modifications to entries, all using . This feature is particularly useful for users without direct access (a high-speed network link) to the AR System server. The engine also returns the results of such requests in that is formatted using plain text, HTML, or XML content. In addition, the engine can process notifications using workflow actions such as filters or escalations. Note: In the 7.0 release, you must install the engine to send notifications from the AR System server. The engine is a stand-alone client program that can be installed and run on any computer system as an independent service. Running as a service, the engine provides the following capabilities: Receiving mail The BMC Remedy Engine receives messages from an account on your company mail server. These messages can include instructions that are then interpreted by the engine and translated into API calls to your AR System server. These instructions can involve modifying form entries, submitting entries, or retrieving multiple entries from your AR System server. Sending mail You can use the engine to send messages, which can include the results of queries, submissions, or modifications to entries contained on your AR System server. These s can be formatted using templates that specify the layout of a message in plain text, HTML, or XML. Processing notifications If you choose when creating a Notify filter or escalation, you can use the engine to send text messages, contents of select fields, or attachments when workflow is triggered. 14 Chapter 1 Overview of the BMC Remedy Engine

15 Administering BMC Remedy Engine The engine can connect to mail servers using the following protocols: Internet Message Access Protocol (IMAP4) When mail arrives, copies of messages are downloaded from the mail server to your local machine. A copy of each message remains on the server. Post Office Protocol (POP3) When mail arrives, messages are downloaded to your local machine and removed from the mail server. Simple Mail Transfer Protocol (SMTP) Used for outgoing mail transmissions. Messaging Application Programming Interface (MAPI) An interface designed for use with Microsoft Windows that enables different applications to work together to distribute . This interface is used primarily with the MS Exchange Server. (Windows only) MBOX A protocol for storage of mail messages on a UNIX platform. Messages are stored in a file under the user name with a file type of mbox. All the settings for the BMC Remedy Engine are stored in forms within an AR System server. All logging information including errors, incoming s, and outgoing s is also stored in separate forms on the AR System server. The forms can be accessed from either BMC Remedy User or a web client. The only information stored by the engine is the location of the AR System server where the forms are stored. Note: You can configure the logs to be stored in a local text file by specifying a handler property in the logging.properties file. For information, see Debugging options for the BMC Remedy Engine on page 231. The engine provides additional options, including the ability to create a variety of templates and to include attachments with messages. It supports Multipurpose Internet Mail Exchange (MIME) types for attachments. About the BMC Remedy Engine 15

16 BMC Remedy Action Request System 7.0 engine terminology Throughout this guide, some familiar terms are used in specific ways. It is important to your understanding of the engine to review these terms and be familiar with their meaning as it pertains to this guide. Mail server account Computer system within your environment running a thirdparty software program that processes incoming and outgoing messages. Examples include the MS Exchange server or the UNIX sendmail program. Mail servers often contain one or more accounts. Refers to a user account on a mail server that permits a user to transmit or receive messages. An account can be associated with one or more addresses. Note: An account is not the same as an address. An account consists of a user name and often includes a password. Users must log in to the mail server using an account before they can send and receive . Mailbox Refers to an entry in the AR System Mailbox Configuration form. The AR System Mailbox Configuration form resides on your AR System server and is discussed in greater detail in Chapter 3, Configuring mailboxes in the BMC Remedy Engine. A mailbox contains all of the information required by the engine to access mail from a mail server or to request that mail be sent by a mail server. As such, a mailbox can contain such information as the name of the mail server, the protocol used by that mail server for either sending or receiving mail, and account information (if required). Mailboxes are configured to be Incoming Mailboxes or Outgoing Mailboxes. 16 Chapter 1 Overview of the BMC Remedy Engine

17 Administering BMC Remedy Engine Incoming mailbox Outgoing mailbox Instructions Mailbox containing the information required by the engine to connect to and read messages from a specific account on a mail server. in this account is treated as if it is directed to the engine. The installation program provides an option for creating and configuring an initial incoming mailbox. You can use this mailbox to get started with the engine; you can then change these settings or configure additional mailboxes using the AR System Mailbox Configuration form. For more information, see Configuring incoming mailboxes on page 59. Mailbox containing the information required by the engine to create and send messages. The engine will use this mailbox to send notifications, send the results of queries, and so on. The installation program provides an option for creating and configuring an initial outgoing mailbox. You can use this mailbox to get started with the engine; you can then change these settings or configure additional mailboxes using the AR System Mailbox Configuration form. For more information, see Configuring outgoing mailboxes on page 53. The term Instruction is used in two ways: In a broader sense, instructions see all the parameters contained in an message that do certain actions; for example, log in to the server, query for all tickets assigned to Joe User, and return the results in HTML format. In a more narrow sense, instructions see a specific set of actions used in an message; for example, Query, Submit, or Modify. The word Instruction can also be used as an alias for Action in a label/value pair. engine terminology 17

18 BMC Remedy Action Request System 7.0 Overview How the engine works This section presents a sample scenario that demonstrates how the engine interacts with the AR System and your mail server. Figure 1-1 presents a sample environment for an engine implementation. Review the figure and pay particular attention to the flow of activity. Figure 1-1: How the engine interacts with the AR System server AR Configuration System Form Mailbox Field 1 Field 2 Field 3 1 AR System admin installs and configures engine 3 parses engine instructions query AR System Server Engine Incoming Mailbox POP3 IMAP4 MBOX MAPI Server Mail Query 4 instructions translated API calls tointo server Outgoing Mailbox SMTP MAPI HD Incident 6.3 Engine Printer Broken Abcd ef ghijkl mno 6 5 Underlying Database Server ticket on queries Incident form HD and results returns Outgoing is formatted and assembled 2 Query sent to mailboxincoming account 1 account 2 7 Users log in to mail server to receive new Shelly Katie Mark 18 Chapter 1 Overview of the BMC Remedy Engine

19 Administering BMC Remedy Engine In the XYZ Company, Shelly needs a list of the latest issues stored in the HD Incident form. She wants the results of this query to be returned in an easyto-read . In addition, Shelly wants to make sure that her co-workers, Katie and Mark, will be copied with the results of this query. All of the steps that the engine and the users must take to make this happen follow. Step 1 The local BMC Remedy administrator installs the engine. During installation, he configures Incoming and Outgoing mailboxes to work with the company mail server. When the installation process is finished and the engine is started, the engine contacts the AR System server. The engine then reads in all of the entries in the AR System Mailbox Configuration form and creates Incoming and Outgoing mailboxes based on the information contained within these entries. Step 2 Step 3 Step 4 Step 5 After the local BMC Remedy administrator notifies the user base that the engine is up and running, Shelly composes an that contains the necessary instructions to the engine to perform a query of the HD Incident form. She sends this message to an account on the company mail server that she knows is used by the engine to poll for incoming mail. The engine, after waiting for a prescribed polling period, logs in to the company mail server using the account information gathered previously during step 1. Because the mailbox information tells the engine that this particular account is to be treated as an Incoming Mailbox, the engine will read the most recent s from this account. The engine uses one of several protocols for reading incoming from the company mail server (POP3, IMAP4, MBOX, or MAPI). It will find and read the that Shelly has sent. When Shelly composed her , she included specifically formatted instructions that could be read and understood by the engine. The engine reads Shelly s , interprets the instructions, and translates them into API calls to the AR System server in an attempt to fulfill her query request. The AR System server responds to the engine API calls with the appropriate query information for the HD Incident form. Overview How the engine works 19

20 BMC Remedy Action Request System 7.0 Step 6 Step 7 The engine, having successfully retrieved the requested information, turns to the Outgoing Mailbox that it created in step 1. It uses the information in the Outgoing Mailbox to format the message to the company mail server. It constructs a message according to formatting instructions contained in the Outgoing Mailbox it is using. After constructing the message, the engine transmits the message to the mail server with instructions to send the message to Shelly, Mark, and Katie using the outgoing protocols (SMTP or MAPI). Shelly, Mark, and Katie log in to the mail server to see if they have new mail. They find the constructed by the engine, which contains a neatly formatted list of the most recent requests. The previous example is a simplified one and is used to illustrate the relationship the engine has to other systems in a simplified environment. Your environment might ultimately differ from the one presented here in many respects. For example, the engine might reside on the same system as the AR System server. Alternatively, you might configure the Incoming Mailbox and Outgoing Mailbox to use the same account on your mail server, and so on. Much of the configuration options available to you will be explained in the upcoming chapters. In addition, as you proceed through this guide, you will learn about many of the other engine features for processing Chapter 1 Overview of the BMC Remedy Engine

21 Administering BMC Remedy Engine Overview Improving the appearance of your To improve the appearance of your , Figure 1-2 shows how the engine can assign HTML templates to outgoing . Figure 1-2: Templates dynamically assigned through workflow AR System Server 3 Underlying Database Server Urgent executes header template filter workflow is dynamically that triggers assigned. Notify action. Templates Field 1 Field 2 Field 3 Template Components 6.3 Engine Field 1 Abcdefg Field 2 Hijklm Field 3 Nopqrst 2 parses engine Instructions instructions. translated then API calls to into server. Incoming Mailbox Mail Server Outgoing Mailbox Engine 4 Field 1 Field 2 Field Engine Abcdefg Hijklm Nopqrst Outgoing assembled according is to formatting header instructions: HTML result template template from Field server values returned account 1 account 2 1 Schema: Action: HD Incident Impact: Submit Urgent Urgent sent incoming to mailbox. Shelly 5 Francie Frontline Urgent sent to Francie Frontline Overview Improving the appearance of your 21

22 BMC Remedy Action Request System 7.0 The local BMC Remedy administrator at XYZ is pleased by the response of the BMC Remedy user community to the engine. Users feel comfortable using to query the AR System server, as well as to submit and modify entries. But he does hear occasional grumbling in the hallway. Why is BMC Remedy so boring? Why can t BMC Remedy look more like what they receive from their favorite online auction website or online bookstore? Figure 1-2 illustrates one possible solution. Realizing the importance of AR System notifications, he takes advanced steps to replace the plain text generated by the engine. To improve its look and feel, he designs better looking HTML pages that will be used as header, footer, result, and content templates. He works with a graphic artist to create interesting bitmaps. Most important, he designs data-driven workflow that dynamically assigns the correct templates based on the ticket s impact. The templates are designed so that users can quickly tell if a ticket s impact is urgent, high, medium, or low. Step 1 Step 2 Step 3 Step 4 Shelly is visiting an important client in Chicago. She desperately needs information from the corporate website within the hour to close an important deal, but the web server is down and her web client keeps returning errors. She composes an with status marked Urgent and sends it to the Incoming mailbox. The engine receives the from the mail server. It parses the instructions in her , and makes the appropriate API calls to the AR System server. When her new request is submitted, the server fires a filter that triggers a Notify action. Under normal circumstances, notifications are formatted with a standard HTML header and result template. But if a submission is marked Urgent, the filter workflow creates an notification with the Urgent header template dynamically assigned. The engine constructs the message according to formatting instructions contained in the Outgoing Mailbox it is using. This message consists of the field values from the HD Incident form (submitter, short description, status, assignee, and so on) along with the header and reply templates that are stored by the AR System server in the AR System Templates form. The engine then transmits the message to the mail server with instructions to send the message to Francie Frontline, the first line Customer Support engineer. 22 Chapter 1 Overview of the BMC Remedy Engine

23 Administering BMC Remedy Engine Step 5 Francie Frontline logs in to the mail server to see if she has new mail. She sees the Urgent constructed by the engine. She clicks the direct access URL in her and the ticket opens in her browser. Because the is marked Urgent, its importance jumps to the top of her To Do list. She troubleshoots and quickly resolves the problem. When Francie marks the ticket as Fixed, the server fires a filter Notify action. Shelly then receives an notification by the system that her web access problems have been solved. She can now access the information she needs to close her sale. For more information, see Dynamically assigning templates to outgoing on page 99. Overview Improving the appearance of your 23

24 BMC Remedy Action Request System Chapter 1 Overview of the BMC Remedy Engine

25 Chapter 2 BMC Remedy Engine installation and setup This chapter describes how to install the BMC Remedy Engine on Windows and UNIX systems. The following topics are provided: Preinstallation steps (page 26) Windows Installing the engine (page 32) UNIX Installing the engine (page 41) Postinstallation steps (page 47) BMC Remedy Engine installation and setup 25

26 BMC Remedy Action Request System 7.0 Preinstallation steps This section describes the preinstallation steps you should complete before you install the engine. Entering information into the installation worksheet Reviewing documentation Print out the worksheets in Appendix A and use them to record information you will need during the installation, including information you obtain during the preinstallation steps. For example, you will need to record the name of the server that will connect to the engine. Before you complete any preinstallation tasks, see the following documentation. What Where Comments Specific information about open issues, localization, and other information for Version 7.0 Most current product compatibility information Action Request System 7.0 Release Notes: supportweb.remedy.com Product Compatibility Matrix: supportweb.remedy.com Before you can access the release notes, you must log in to the Customer Support Website. Before you can access the compatibility matrix, you must log in to the Customer Support Website. Installing components Install the following before you install the engine: A compatible AR System server A compatible Java Runtime Environment (JRE). See the product compatibility matrix on the Customer Support website for more information. 26 Chapter 2 BMC Remedy Engine installation and setup

27 Administering BMC Remedy Engine Windows Preinstallation tasks This section describes the preinstallation tasks you should complete before you install the engine on Windows. Environment variables Set any relevant environment variables to control the installation. For example, set the PATH and CLASSPATH environment variables to use the correct version of Java. See the Installing guide for more information about environment variables. Secure Socket Layer option Check to see if your environment requires the Secure Socket Layer (SSL) option. For more information, see Configuring SSL for the engine on page 76. MAPI and MBOX preparation The tables in this section explain the steps you must follow to set up the system if you are using the MAPI or MBOX mail protocols. You do not need to prepare the system if you are using the IMAP4, POP3, or SMTP protocols. Note: MAPI users only: If you are upgrading your engine from a previous engine version, and you do not need to change your existing MAPI configuration information, skip this section and go to Windows Installing the engine on page 32, or UNIX Installing the engine on page 41. MAPI preparation steps To prepare the system to use the MAPI protocol, you must install MS Exchange server and client, create and configure a Windows domain user account, and then create an MS Exchange mailbox for use with the engine only. While logged in as the Windows domain user account, you must create an MS Exchange profile on the same computer where you plan to install the engine. Preinstallation steps 27

28 BMC Remedy Action Request System 7.0 Note: You must be a Windows domain administrator or MS Exchange administrator to perform these steps. What Where Comments Install components MS Exchange server MS Exchange client At one of the following locations: Same domain as the engine domain. A domain with the appropriate trust relationship to the engine domain. Same machine as the machine where you plan to install the engine. The clients contain the libraries that the protocols will use. See the product compatibility matrix for more information about compatible clients for the engine. Create and configure a Windows domain account Create a Windows domain user account. Assign group and domain membership to the domain user account. At one of the following locations: On the same domain as the engine. On a domain with appropriate trust relationships. At one of the following locations: On the same domain as the engine. On a domain with appropriate trust relationships. Enter the name of this user in the Windows Configuration worksheet at: Windows Incoming mailbox: Server User Windows MAPI logon settings: Windows NT User Group membership: Local administrator s group (active directories only). Domain membership: engine domain or Exchange Server domain 28 Chapter 2 BMC Remedy Engine installation and setup

29 Administering BMC Remedy Engine What Where Comments Grant the domain user advanced rights. On the computer where you plan to install the engine. Advanced rights: Act as Part of the Operating System Log on as a Service Note: Active directories only: Make sure that the Effective Rights option shares the correct advanced rights. Create and configure an MS Exchange profile Create an MS Exchange profile. Configure the profile. Check your profile setup Log in as the domain user you created earlier. Using the MS Outlook client, send and receive s to verify that the MS Exchange profile is functioning correctly. On the computer where you plan to install the engine. From the computer where you plan to install the engine. Log in as the domain user to create this profile. Enter this value in the Windows Configuration worksheet entry: MAPI - Profile. Configure the profile to: Work exclusively with the engine. Be accessible by the Windows domain user account you created earlier in the sub-table section: Create and configure a Windows domain account. Point to the MS Exchange server and mailbox. Preinstallation steps 29

30 BMC Remedy Action Request System 7.0 MBOX preparation steps To prepare the system for using the MBOX protocol: Create an account and account user. Give the account user full read and write permissions to relevant directories and files. Verify that the account can send and receive s. See Appendix C, Setting up UNIX mailboxes. BMC Remedy mail server upgrade If you are upgrading from BMC Remedy mail server, you should: 1 Complete the preinstallation steps in the preinstallation section that are relevant to the mail protocol you will choose for the engine. 2 Transfer existing information from the ar.cfg or armaild.cfg files to the worksheet. Use the following mapping table as a guide. BMC Remedy mail server information ExchangeNTAccount ExchangeNTDomain equivalent to the domain user Exchang box Mapping equivalent in the engine Enter this information into the Windows NT User line of the worksheet. Enter this information into the Windows NT Domain line of the worksheet. Enter this information into the Display Name line of the worksheet. 3 Obtain templates, including identifying: All forms used in templates. Default settings the templates rely on. 4 Verify that the Mailntfy folder is empty. If it is not, let the old BMC Remedy Mail Server finish processing the remaining notifications in the Mailntfy directory, until it is empty. 30 Chapter 2 BMC Remedy Engine installation and setup

31 Administering BMC Remedy Engine 5 Stop and disable the BMC Remedy Mail Server. See Appendix D, Upgrading option parameters for information about converting your old configuration parameters to their functional equivalent in the 7.0 engine. UNIX Preinstallation tasks Check if the preinstallation steps in this section pertain to your installation. Environment variables Set any relevant environment variables to control the installation. See the Installing guide for more information about setting and customizing UNIX options. Upgrades from the BMC Remedy Engine Use the d.sh stop command to stop the existing engine before you install the new engine. If you do not stop the existing engine, none of the open engine files and libraries will be updated. If the d.sh stop command fails to stop the engine, comment out the startup of the engine in the /etc/arsystem/hostname/ armonitor.conf file, and then stop and restart the AR System server. (For more information, see Postinstallation steps on page 47.) Upgrading from engine version 5.1 or You must be running on the (or later) version of the engine to upgrade to version 7.0. Installing as a non-root user Installing as a non-root user is not recommended. This section lists limitations and actions you should follow to install the engine as a non-root user. Creating directories Create the logging.properties and javamail.providers files. Preinstallation steps 31

32 BMC Remedy Action Request System 7.0 Writing to files Only root users can write to the armonitor.conf file. Because non-root users do not have permission to write to this file, the installer creates a temporary file instead (armonitor.conf_temp). After installation, you must append the contents of the armonitor.conf_temp file to the armonitor.conf file. Deleting existing files If you have AR System installed, delete the /tmp/migfiles directory. Allocating permissions Give the non-root user permission to the following directories: MBOX mail directory and all its contents JRE (Java Runtime Environment) directory and all its contents, especially the <Java_home>/jre/lib directory For more information about installing as a non-root user, see the Installing guide. Windows Installing the engine Loading the software After you have completed the worksheet and the preinstallation sections, use the steps in this section to install the engine on Windows. This section describes the steps to access the installation software from a CD or from the Web. To access the installation software 1 From the CD: a Log in to Windows as an administrator and insert the CD into the drive. b If autorun is enabled, the CD browser opens. Click Install Products and then click BMC Remedy Engine. c If the CD browser does not start, run the engine installer, d.exe. 32 Chapter 2 BMC Remedy Engine installation and setup

33 Administering BMC Remedy Engine 2 From ESD: a If you downloaded the engine to a location that is not the installation location, copy the downloaded directory and its contents to the computer where you will install the engine. b From the download directory, run the file d.exe. When you run this file, the installation files are unpacked into a temporary directory and the Setup program starts. Installing the engine This section provides the steps to install the engine on a computer that has no existing engines (new install), and on a computer with one or more existing engines installed (upgrade or overwrite). The section is divided into the following subsections: Entering basic information on page 33, which describes steps to enter server-related information, including port numbers. Entering configuration information on page 35, which describes steps to enter configuration information for incoming and outgoing mailboxes. Completing the installation on page 40, which describes the steps to complete the installation. To accept the defaults for any of the options in the following procedures, click Next. Entering basic information This section provides the steps to start the installation and enter product directory and licensing information. To enter basic information 1 After you load the media, the Welcome screen appears. Click Next to display the Software License Agreement screen. 2 Click the I Agree button to accept the software license agreement and to display the Choose Destination Location screen. Windows Installing the engine 33

34 BMC Remedy Action Request System Click Next to accept the default installation directory or click Browse to choose another directory, and then click Next. Upgrades or overwrites only: By default, the engine will be installed in the installation directory of the existing engine. You can choose to install the engine into a different directory. New installs only: By default, the engine will be installed in the C:\Program Files\AR System\AR directory. You can choose to install the engine into a different directory. The AR Server to Support Server screen appears. 4 Enter the following information in the fields: a AR Server Name Name of the AR System server that this engine will connect to. WARNING: For multiple AR System servers on the same machine only: To maintain the correct dependency relationship between your engine and its dedicated AR System server, make sure you enter the correct AR System server for the engine you are installing. b Port Number TCP port number for the AR System server that the engine will connect to. You do not have too enter a value if the AR System server is using a portmapper. Note: You must enter a TCP port if the engine and the AR System server are on the opposite sides of a firewall. c For more information about registering portmappers, see the Installing guide. RPC Port Number RPC port number for the AR System server. Enter an RPC port only if you have already configured a private server to use with the engine. For more information about private servers in the AR System, see the Configuring guide. 34 Chapter 2 BMC Remedy Engine installation and setup

35 Administering BMC Remedy Engine 5 Click Next to display the Administrator Logon Information Required screen. Enter an AR System Administrator user name and password. The user name must have Administrator privileges on the AR System server. This user name will be used only during installation to import the necessary AR System engine forms and workflow. 6 Click Next to display the Application Service Password screen. 7 Enter the password designated for this server. An Application Service password is required. This password is set in the Server Information dialog box in BMC Remedy Administrator. 8 Click Next to display the Start Copying Files screen. The installer displays installation-related messages. 9 Click Next to begin copying files. Entering configuration information This section describes the prompts for entering engine configuration information. Incoming mailboxes can be configured using MAPI, POP3, or IMAP4. Outgoing mailboxes can be configured using MAPI or SMTP. After the installer copies the files, the AR System Mailbox Configuration screen appears. Choose one of the following options: 1 Click No to configure the engine after installation. Use this option if you are upgrading or overwriting and you do not want to change the configuration settings. See the configuration chapter for more information about configuring the engine after installation. Go to Completing the installation on page Select Incoming, Outgoing, or Incoming and Outgoing from the Mailbox Function menu to configure incoming mailboxes, outgoing mailboxes, or both. Use this option if you are: Performing a new install. Creating additional mailboxes. Upgrading from BMC Remedy mail server (pre-5.1). Windows Installing the engine 35

36 BMC Remedy Action Request System 7.0 If you selected Outgoing only, go to Configuring your outgoing mailbox on page 38. If you selected Incoming, or Incoming and Outgoing, go to Configuring your incoming mailbox. Configuring your incoming mailbox Follow the steps in this section to configure your incoming mailbox. To configure your incoming mailbox 1 Click Next to display the BMC Remedy Mailbox Configuration - Incoming Mailbox screen. Different choices become enabled when you select the mail protocol (Server Type). Figure 2-1: Incoming Mailbox screen 36 Chapter 2 BMC Remedy Engine installation and setup

37 Administering BMC Remedy Engine 2 MAPI only: Enter the following information in the fields: a Mailbox Name Enter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. b Server Type Select MAPI from the menu. c Profile Enter the name of the MS Exchange profile you created in the Windows Preinstallation tasks section on page 27. If you chose to configure only an incoming mailbox, go to Entering MAPI logon settings on page 39. If you chose to configure both incoming and outgoing mailboxes, go to Configuring your outgoing mailbox on page POP3 or IMAP4 only: Enter the following information in the BMC Remedy Mailbox Configuration - Incoming Mailbox screen fields: a Mailbox Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. b Server Type Select POP3 or IMAP4. c SSL Check the box to enable Secure Socket Layer (SSL). d Server Name/IP Enter the name or IP address of your company s mail server. e f g h Server Port Enter the mail server port number. Server User Enter the name of the user of the account. Server Password Enter the password corresponding to the server user. If you chose to configure both an incoming and outgoing mailbox, go to Configuring your outgoing mailbox on page 38. If you chose to configure only an incoming mailbox, go to Completing the installation on page 40. Windows Installing the engine 37

38 BMC Remedy Action Request System 7.0 Configuring your outgoing mailbox Follow the steps in this section to configure your outgoing mailbox. To configure your outgoing mailbox 1 Click Next to display the BMC Remedy Mailbox Configuration - Outgoing Mailbox. a MAPI only: Enter the following information in the fields: Mailbox Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Outgoing. Display Name Enter a descriptive name that appears in the From: line of outgoing s. Address Enter the address of the server user that you entered previously in step f. For example, if you entered a display name of ARSystem and an address of [email protected], the From: line would be: From: ARSystem [[email protected]] Server Type Select MAPI from the menu. Profile Enter the name of the MS Exchange profile that is dedicated for use with the engine. Go to To enter MAPI logon settings on page 39. b SMTP only: Enter the following information in the fields: Mailbox Name Enter a descriptive name for your outgoing mailbox. For example, enter AR - Outgoing. Display Name Enter a descriptive name that appears in the From: line of outgoing s. Address Enter the full address of the mailbox user. If you entered a display name of ARSystem and an address of [email protected], the From: line would be: From: ARSystem [[email protected]] 38 Chapter 2 BMC Remedy Engine installation and setup

39 Administering BMC Remedy Engine Server Type Select SMTP from the menu. SSL Check the box to use Secure Socket Layer (SSL), if applicable. Server Name/IP Enter the name or IP address of your company s mail server. Server Port Enter the mail server port number (default is 25). Server User Enter the name of the user of the account (null if not applicable). Server Password Enter the password corresponding to the server user (null if not applicable). Go to Completing the installation on page 40. Entering MAPI logon settings Follow the steps in this section to enter MAPI logon settings. You must enter these settings if you use MAPI. To enter MAPI logon settings 1 Click Next to display the Engine MAPI Logon Settings screen. Figure 2-2: MAPI Logon Settings screen Windows Installing the engine 39

40 BMC Remedy Action Request System 7.0 Enter the following information in the fields: a Windows NT User Enter the name of the Windows domain user that you created in the Windows Preinstallation tasks section on page 27. This user has access to the Exchange profile mailbox and also has Windows NT domain permissions to start the engine as a service. b Password Enter the password corresponding to the Windows NT User. c Windows NT Domain Enter the Windows NT domain. Note: To configure more incoming and outgoing mailboxes, see Chapter 3, Configuring mailboxes in the BMC Remedy Engine. Completing the installation 1 Click Next to complete copying files and to display the Setup Complete dialog box. 2 In the Setup Complete dialog box, choose Yes to restart your computer (optional) and click Finish to complete the installation. The remaining files are copied to your system. If you have problems, see Stopping and starting the AR System server on page Chapter 2 BMC Remedy Engine installation and setup

41 Administering BMC Remedy Engine UNIX Installing the engine Loading the software After you have completed the steps in the section UNIX Preinstallation tasks on page 31 and the UNIX installation worksheets in Appendix B, use the steps in this section to install the engine on UNIX. This section describes the steps to access the installation software from a CD or from the Web. To access the installation software 1 From the CD: Mount the CD locally or remotely. Use the following command to change to the directory containing the engine installation script: # cd <CD-ROM_mount_point>/arsystem The default mount point is /cdrom. See the Installing guide for more information about mounting a CD. 2 From Electronic Software Distribution (ESD): Download the *.tar.gz file to the arsystem directory of the computer where you are installing the engine. Installing the engine This section provides the steps to install the engine on a computer that has no existing engines (new install), and on a computer with one or more existing engines installed (upgrade or overwrite). The section is divided into the following subsections: Entering basic information on page 42, which describes steps to enter server-related information, including port numbers. Entering configuration information on page 35, which describes steps to enter configuration information for incoming and outgoing mailboxes. Completing the installation on page 40, which describes the steps to complete the installation. UNIX Installing the engine 41

42 BMC Remedy Action Request System 7.0 To accept the defaults for any of the options in the following procedures, press ENTER. Note: These procedures do not display the UNIX prompts, but rather the steps correspond to sequential actions that you must take during installation. The script writes a log file to: /usr/tmp/ed_install.log. Entering basic information This section provides the steps to start the installation and enter product directory and licensing information. To enter basic information 1 Log in as the root user. To install the software without root privileges, see Installing as a non-root user on page Run the ed_install script, located in the arsystem directory. #./ed_install 3 At the prompt to install the BMC Remedy Engine 7.0, enter y. The installer displays logging and system messages. 4 At the product directory prompt, enter the name of the directory where the CD-ROM is mounted and where the ed_install file is located. Typically, the product directory is called arsystem. 5 At the license agreement prompt, press one of the following keys: Press ENTER to view the entire licensing agreement. Press q to return a prompt that allows you to accept, reject, or re-read the agreement. If you do not accept the terms of the licensing agreement, the installation terminates. 42 Chapter 2 BMC Remedy Engine installation and setup

43 Administering BMC Remedy Engine 6 At the Java prompt that asks if you have Java SDK installed, choose one of the following actions: a Type n to terminate the installation if you do not have a compatible Java SDK installed. Install a compatible Java product and restart the installation. b Type ENTER if you have already installed a compatible Java product. 7 At the Java installation directory prompt, enter the directory path to your Java root directory and confirm the location. A typical path is: /usr/java<version>/<root_directory_location> The root directory contains the /bin and /jre directories. 8 At the AR System server name prompt, enter and confirm the name of the server that the engine will connect to. This server can also be a private server that you have already configured. For more information about private servers, see the Configuring guide. WARNING: For multiple AR System servers on the same machine only: To maintain the correct dependency relationship between your engine and its dedicated AR System server, make sure you enter the correct AR System server for the engine you are installing. 9 At the TCP port for the AR System server prompt, perform one of the following tasks: Press ENTER to accept the defaults if you have registered the server you chose in step 8 with a portmapper and you do not want to assign a port number. Enter a TCP port for the AR System server that you will use with the engine you are installing. 10 Confirm your selection. Note: You must specify a TCP port if the engine is on the other side of a firewall from the AR System server. For more information about ports, see the Installing guide. UNIX Installing the engine 43

44 BMC Remedy Action Request System At the RPC port for the AR System server prompt, perform one of the following tasks: Press ENTER to accept the defaults if you have registered the server you chose in step 8 with a portmapper and you do not want to assign a port number. Enter the RPC port for the AR System server you entered in step 8 on page Confirm your selection. For more information about ports, see the Installing guide. 13 At the BMC Remedy Admin User Name prompt, enter and confirm the AR System Administrator user name and password. The AR System Administrator has permissions to import forms and workflow. If your AR System server is not running, the installer prompts you to check the server. Make sure your AR System server is running before proceeding. 14 At the Application Service password prompt, enter the Application Service Password designated for this system. An Application Service password is required. This password is set in the Server Information dialog box in BMC Remedy Administrator. 15 At the configuration prompt, press one of the following keys: Enter n to configure the engine after installation. Use this option also if you are upgrading and you do not want to change the configuration settings. See the configuration chapter for more information about configuring the engine after installation. Go to Completing the installation on page 47. Enter y to configure the engine during the installation. Use this option if you would like to send and receive immediately after installation, or you are upgrading from BMC Remedy mail server. After you install, you can change configuration values in the AR System Mailbox Configuration form. 44 Chapter 2 BMC Remedy Engine installation and setup

45 Administering BMC Remedy Engine 16 At the mailbox function prompt, press one of the following keys: Enter n to skip the configuration steps. Go to Completing the installation on page 47. Enter b to configure incoming and outgoing mailboxes. Enter i to configure the incoming mailbox only. Enter o to configure the outgoing mailbox only. 17 At the Secure Socket Layer (SSL) prompt, enter y if you are using SSL. Entering configuration information This section describes the prompts for entering engine configuration information. On UNIX, incoming mailboxes can be configured using POP3, IMAP4, or MBOX. Outgoing mailboxes can be configured using SMTP. Configuring an incoming mailbox Use the steps in this section to configure an incoming mailbox. To configure your incoming mailbox Enter the following information at the prompts: 1 POP3 or IMAP4 only: a Mailbox Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. b Server Type Select POP3 or IMAP4. c SSL Check the box to enable Secure Socket Layer (SSL). d Server Name/IP Enter the name or IP address of your company s mail server. e Server Port Enter the mail server port number (default is 110). f g h Server User Enter the name of the user or administrator of the account. Server Password Enter the password corresponding to the server user. If you chose to configure both an incoming and outgoing mailbox, go to Configuring your outgoing mailbox next. If you chose to configure only an incoming box, go to Completing the installation on page 40. UNIX Installing the engine 45

46 BMC Remedy Action Request System MBOX only: a Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. b Server name Enter the name of the server that will connect to the engine. c d Server Type Select m for MBOX. Incoming Mailbox Path Enter the full path to your incoming mailbox. Enter the full path to the incoming mailbox MBOX file for the user account. For example: /usr/spool/mail/arsystem where ARSystem is the MBOX file name. To confirm that the path you entered is the correct path, perform one of the following tasks: Look in your /etc/aliases file. Run the following command: /usr/lib/sendmail -bv -v <mailbox_user> e Incoming User Home Path Enter the full path of the user home directory. For example: /home/arsystem. If you chose to configure both an incoming and outgoing mailbox, go to Configuring your outgoing mailbox on page 38. If you chose to configure only an incoming box, go to Completing the installation on page 40. Configuring your outgoing mailbox The next prompts in the sequence are related to outgoing mailbox configurations with SMTP. To configure your outgoing mailbox with SMTP Enter the following information in the fields: a Mailbox Name Enter a descriptive name for your outgoing mailbox. For example: AR - Outgoing. b Display Name Enter a descriptive name that appears in the From: line of outgoing s. 46 Chapter 2 BMC Remedy Engine installation and setup

47 c d Administering BMC Remedy Engine Address Enter the full address of the administrator or owner of the mailbox. If you previously entered a display name of ARSystem and an address of [email protected], the From: line would be: From: ARSystem [[email protected]] Server Name/IP Enter the name or IP address of your company s mail server. e Server Port Enter the mail server port number (default is 25). f g Server User Enter the name of the user or administrator of the account (null if not applicable). Server Password Enter the password corresponding to the server user (null if not applicable). Go to Completing the installation on page 40. Completing the installation To complete the installation, enter the installation directory at the prompt. The script displays a list of extracted files and error messages (if there are any). Note: After you complete the installation, restart the server. Restarting the server will restart the engine. Postinstallation steps This section describes optional postinstallation steps. Starting and stopping the engine The engine is configured to start automatically in both UNIX and Windows. If the engine fails to start automatically, use the instructions in this section to start it manually. This section also includes instructions to stop the engine manually. Postinstallation steps 47

48 BMC Remedy Action Request System 7.0 Note: The engine will also stop if you stop the AR System server manually from the Services window. However, the engine will not start again when you restart the AR System server you must restart the engine manually. UNIX Starting and stopping the engine Use the following instructions to start and stop the engine on UNIX. To start the engine on UNIX manually 1 Change directories to the engine installation directory. cd < _engine_install_dir> 2 Enter one of the following commands to start the engine manually: d.sh start & or # nohup d.sh start & To stop the engine on UNIX manually 1 Enter the following command to change directories to the engine installation directory: cd < _engine_install_dir> 2 Enter the following commands to stop the engine: # d.sh stop & After you issue this command, AR Monitor stops the engine service and immediately restarts it automatically. If the d.sh command fails to stop the engine, comment out the following line in the armonitor.conf file, then reissue the d.sh command: /etc/arsystem/<server_name>/armonitor.conf Windows Starting and stopping the engine Use the following instructions to start and stop the engine on Windows. 48 Chapter 2 BMC Remedy Engine installation and setup

49 Administering BMC Remedy Engine To start and stop the engine on Windows manually 1 From the Services window: a Choose Start > Settings > Control Panel > Administrative Tools > Services. b Select the BMC Remedy Engine service. c Right-click the service and choose Start or Stop. The service will start or stop immediately. 2 From a command line: a Change directories to the engine installation directory. cd < _engine_install_dir> b Enter one of the following commands to start the engine: start or c java -cp daemon.jar;arapi70.jar;arutil70.jar;activation; jar;mail.jar;imap.jar;smtp.jar;pop3.jar; com.remedy.arsys. daemon. daemon Enter the following command to stop the engine: stop Note: MAPI mailbox users only: If you did not configure your MAPI mailbox during installation, change the engine login information in the Services window to your Windows user account. Postinstallation steps 49

50 BMC Remedy Action Request System Chapter 2 BMC Remedy Engine installation and setup

51 Chapter 3 Configuring mailboxes in the BMC Remedy Engine This chapter explains how to create and configure engine mailboxes and how to set security options. The following topics are provided: Overview configuration (page 52) Configuring outgoing mailboxes (page 53) Configuring incoming mailboxes (page 59) Testing your mailbox configuration (page 65) Configuring security (page 69) MAPI Saving outgoing notifications (page 75) Changing the form entry interval time (page 76) Configuring SSL for the engine (page 76) Configuring mailboxes in the BMC Remedy Engine 51

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

53 Administering BMC Remedy Engine Configuring outgoing mailboxes This section describes procedures to create and configure outgoing mailboxes. The configuration information you choose in these procedures is stored in the AR System Mailbox Configuration form. You must create at least one outgoing mailbox to process outgoing mail. Figure 3-1: Setting default outgoing mailbox Set default outgoing mailbox Based on the configuration options you choose in this section, the engine creates and sends messages. Outgoing messages might include results from actions specified in incoming messages, such as query or workflow results. Outgoing mailboxes can also be linked to incoming mailboxes, such that the results of any actions from a specific incoming mailbox are sent to the specified outgoing mailbox. Note: To use notifications with , you must designate one mailbox as your default notification mailbox. Configuring outgoing mailboxes 53

54 BMC Remedy Action Request System 7.0 Basic outgoing mailbox configuration This section describes how to perform a basic configuration for your outgoing mailbox. The following figure shows an example of the Basic Configuration tab for the SMTP protocol. Figure 3-2: Basic Configuration tab for outgoing mailboxes Outgoing mailboxes support the following mail protocols: MAPI and SMTP. To create a basic configuration for your outgoing mailbox 1 MAPI only: a Enter the following information in the fields above the tabs: Mailbox Name Enter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Outgoing. Mailbox Function Select Outgoing. Status Select Enabled to enable the options. b Enter the following information in the Basic Configuration tab: Server Type Select MAPI from the menu. Polling Interval Select a polling interval for the engine to check for new incoming from the mail server. Profile Name Enter the name of the MS Exchange profile you created in the preinstallation section of the installation chapter. This field is required because a profile is used to see MAPI account configuration information. For more information about MS Exchange profiles, see your MS Exchange documentation. 54 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

55 c Click Save. 2 SMTP only: a Administering BMC Remedy Engine Enter the following information in the fields above the tabs: Mailbox Name Enter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Outgoing. Mailbox Function Select Outgoing. Status Select Enabled to enable the options. b Enter the following information in the Basic Configuration tab: c Server Type Select SMTP from the menu. Polling Interval Select a polling interval for the engine to check for new incoming from the mail server. SSL Check the box to enable Secure Socket Layer (SSL). For more information, see Configuring SSL for the engine on page 76. Server Name/IP Enter the name or IP address of your company s mail server. Server Port Enter the mail server port number, or click Set Default Server Port to accept the default port. Server User Enter the name of the user of the account. The engine uses this account to authenticate requests for outgoing messages Server Password Enter the password corresponding to the server user. Enter a user and password only if your mail server requires authentication information before sending out . Click Save. Configuring outgoing mailboxes 55

56 BMC Remedy Action Request System 7.0 Advanced outgoing mailbox configuration This section describes how to perform an advanced configuration for your outgoing mailbox in the Advanced Configuration tab. Figure 3-3 shows an example of the Advanced Configuration tab. Figure 3-3: Advanced Configuration tab for outgoing mailboxes An outgoing mailbox can be configured to use default templates, including a default header, footer, content, results, or status template. You can choose to configure your mailbox to use defaults in one or more of the categories; for example, you can choose to specify a default header and footer template but no content template. Only one default template of each type can be specified for a mailbox. Templates must already be stored in the AR System Templates form. Outgoing mailboxes support the MAPI and SMTP mail protocols. Important: Before you enter your choices, consider reviewing the information about advanced configuration settings in Chapter 6, Using templates. 56 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

57 Administering BMC Remedy Engine To create an advanced configuration for your outgoing mailbox 1 Enter the following information in the fields at the top of the tab: a Associated Mailbox Name Enter the name of an incoming mailbox to associate with your outgoing mailbox. This incoming mailbox receives instructions and must have already been created. Note: To use modify actions, you must have an incoming and outgoing mailbox configured, and these two mailboxes must be associated with one another. For more information, see Modify action on page 195. b Default Outgoing Mailbox Select Yes to make this outgoing mailbox the default mailbox. The default mailbox routes all that does not have a specified outgoing mailbox associated with it. c d e f Display Name Enter a descriptive name that appears in the From: line of outgoing s. MAPI only: This option is not used. Address Enter the address of the server user that you created in step b on page 55 For example, if you entered a display name of ARSystem and an address of [email protected], the From: line would be: From: ARSystem [[email protected]] MAPI only: This option is not used. Reply To Address Specify an address where replies to your outgoing s should be sent, or accept the default server user address already in this field. MAPI only: This option is not used. Organization Enter the name of the organization or company if your client displays your organization s name. Configuring outgoing mailboxes 57

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

59 Administering BMC Remedy Engine Configuring incoming mailboxes This section describes procedures to create and configure incoming mailboxes. The configuration information you choose in these procedures is stored in the AR System Mailbox Configuration form. Based on this information, the engine polls incoming mailboxes for new messages, processes the messages, parses the contents (if the incoming mailbox is set to parse), and performs the actions specified in the messages, such as modifying requests or executing queries. Incoming mailboxes support the following mail protocols: MAPI, POP3, IMAP4, and MBOX. Basic incoming mailbox configuration Enter the information to create a basic configuration for your incoming mailbox in the Basic Configuration tab on the AR System Mailbox Configuration form. The following figure shows an example of this tab. Figure 3-4: Basic Configuration tab for incoming mailboxes During basic configuration, you enter the following information: Mailbox information, such as the mailbox name Server information, such as the mail protocol associated with the server and the server port number Configuring incoming mailboxes 59

60 BMC Remedy Action Request System 7.0 To create a basic configuration for your incoming mailbox 1 MAPI only: a Enter the following information in the fields above the tabs: Mailbox Name Enter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. Mailbox Function Select Incoming. Status Select Enabled to enable the options. b Enter the following information in the Basic Configuration tab: Server Type Select MAPI from the menu. Polling Interval Select a polling interval for the engine to check for new incoming from the mail server. Profile Name Enter the name of the MS Exchange profile you created in the preinstallation section in the installation chapter. This field is required because a profile is used to see MAPI account configuration information. For more information about MS Exchange profiles, see your MS Exchange documentation. 2 POP3 or IMAP4 only: a Enter the following information in the fields above the tabs: Mailbox Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. Mailbox Function Select Incoming. Status Select Enabled to enable the options. b Enter the following information in the Basic Configuration tab: Server Type Select POP3 or IMAP4. Polling Interval Select a polling interval for the engine to check for new incoming from the mail server. SSL Check the box to enable Secure Socket Layer (SSL). For more information, see Configuring SSL for the engine on page Chapter 3 Configuring mailboxes in the BMC Remedy Engine

61 Administering BMC Remedy Engine Server Name/IP Enter the name or IP address of your company s mail server. Server Port Enter the mail server port number. Server User Enter the name of the user of the account. Server Password Enter the password corresponding to the server user. 3 MBOX only: a Enter the following information in the fields above the tabs: Mailbox Name Enter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystem - Incoming. Mailbox Function Select Incoming. Status Select Enabled to enable the options. Server Type Select MBOX. Polling Interval Select a polling interval for the engine to check for new incoming from the mail server. Inbox Path Enter the complete path to the MBOX file that corresponds to the user account. For example, enter /usr/spool/mail/arsystem, where ARSystem is the file name. 4 When you have selected or entered your choices, click Save. Advanced incoming mailbox configuration Enter the information to create an advanced configuration for your incoming mailbox in the Advanced Configuration tab on the AR System Mailbox Configuration form. The following figure shows an example of this tab. Configuring incoming mailboxes 61

62 BMC Remedy Action Request System 7.0 Figure 3-5: Advanced Configuration tab for incoming mailboxes Advanced configuration steps are shared by all mail protocols (MAPI, POP3, IMAP4, and MBOX). During advanced configuration, you enter information about associated mailboxes, templates, and forms, and information related to mailbox security. Important: Before you enter your choices, consider reviewing the information about advanced configuration settings in Chapter 6, Using templates. To create an advanced configuration for your incoming mailbox 1 Select an outgoing mailbox from the Associated Mailbox Name list. This mailbox is used to reply to incoming s that require responses, such as incoming queries. Note: To use modify actions, you must have an incoming and outgoing mailbox configured, and these two mailboxes must be associated with one another. For more information, see Modify action on page Chapter 3 Configuring mailboxes in the BMC Remedy Engine

63 Administering BMC Remedy Engine 2 Complete the Action Configuration section: a Action Select Parse to enable the engine to detect and process instructions included in an incoming message. This is required if you use templates to perform Submit, Modify, or Query actions. See Using label/value pairs in templates on page 191 and Incoming and outgoing mail templates on page 185 for more information about templates and parsing. b Upgrades from BMC Remedy Mail Server only; original template format Use Original Template Format: Select Yes to enable original parsing system processing. Original parsing ignores special HTML fields, XML formats, and data entered in an invalid format, such as a character string in a number field. If this option is enabled, the engine returns an error when it encounters these types of fields or formats. Select No to enable normal parsing. Note: If you choose No, you must make sure that multiple lines in s are encapsulated with the [$$ and $$] multiple-line delimiters. c d Reply with Result Select Yes to enable the engine to return the results of an action in an . Reply with Result allows the sender to know if the incoming succeeded or failed. For more information, see Action label on page 194. Reply with Entry Select Yes to return the complete entry of a submit or modify action. Note: To include attachments in an , you must use a template. For more information, see Including attachments with incoming on page 154. e Enable Modify Actions Select Yes to enable the engine to modify existing entries. Configuring incoming mailboxes 63

64 BMC Remedy Action Request System 7.0 f Default Workflow Form Enter the name of the default form on which the engine executes instructions from the incoming message. For example, the engine might execute queries, form-entry modifications, and form submittals. Note: If you define a default workflow form, then incoming templates do not require the Form (or Schema) label. For more information, see Form label on page 192. g Force Default Workflow Form Select Yes to confine all instructions from the incoming message to the form that you specified in the Default Workflow Form field. Note: If an incoming template specifies a schema, the schema will not be processed and the default workflow form instead will be used. 3 Complete the Incoming Security Configuration section: In these fields, you specify the level of security to be applied to messages to this mailbox. This information is used to determine which AR System user information to apply when executing instructions parsed from an incoming . You can apply any or all of these security options, depending on the level of security you want. a Use Security Key Select Yes to enable a security key for incoming . When you enable this option, the information is added to the Security form, so you do not have to supply the user name and password in the incoming . If you choose to enable the option, you must create and configure the security key. See Configuring incoming mailbox security on page 69. b Use Supplied User Information Select Yes to use AR System server login information from the incoming message. If this option is enabled, the engine uses this login information to execute instructions in the incoming message, such as instructions to modify requests or submit queries. For more information about login syntax, see Login, Password, and TCP Port labels on page Chapter 3 Configuring mailboxes in the BMC Remedy Engine

65 Administering BMC Remedy Engine c Use From Address Select Yes to use the address of the sender as a form of authentication. If this option is enabled, the engine returns an error if the sender s address is different from the address stored in the AR System User form. 4 When you have selected or entered your choices, click Save. Testing your mailbox configuration You must test your mailbox configurations to make sure that your mailbox communicates to your mail server correctly. Note: If your engine requires a security key to authenticate incoming , skip this section and see Configuring security on page 69. Testing your outgoing mailbox Use the following steps to verify that you can send from your outgoing mailbox. If you complete the steps successfully, your outgoing mailbox is configured correctly. If you are unable to complete the steps, see Chapter 7, Troubleshooting, for more information. To test your outgoing mailbox 1 In BMC Remedy User, open the AR System Messages form in New mode. 2 In the AR System Messages form, create a message as follows: a Mailbox Name Select the name of the outgoing mailbox to test. b Message Type Select Outgoing. c Message Tab Enter addresses for the From: and To: fields. Note: Choose an address that you can access with a third-party utility, such as Microsoft Outlook. d Message Tab Enter a subject line and body content. Testing your mailbox configuration 65

66 BMC Remedy Action Request System Click Send. 4 Open the AR System Messages form in search mode. 5 Perform a query for the message you sent. 6 In the results table, check for the following information: a An entry corresponding to the message. b The value under the Send Message column = Yes. A Yes value indicates that the outgoing mailbox has queued your to be sent. Figure 3-6: Entry created of outgoing message 7 Open the AR System Mailbox Configuration form in search mode. 8 Wait for the amount of time specified in the Polling Interval for the Outgoing Mailbox you are testing (see the Basic Configuration tab). Tip: Set the interval to one minute to view results promptly. 9 Open the AR System Messages form in search mode. 10 Enter the name of the outgoing mailbox to test and click Search. 11 In the results table, check for the following information: a An entry corresponding to the message exists in the table. b The value in the Send Message column is Sent. c The value in the Date Sent column is the precise time that the message was sent to the mail server. 66 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

67 Administering BMC Remedy Engine Figure 3-7: Entry created for the outgoing message 12 Using a third-party client, verify that the message was sent to the To address you specified in step c on page 65. If your test fails, see Chapter 7, Troubleshooting. Testing your incoming mailbox Use the following steps to verify that you can receive in your incoming mailbox. If you complete the steps successfully, your incoming mailbox is configured correctly. If you are unable to complete the steps, see Chapter 7, Troubleshooting, for more information. Before you perform the test, obtain the correct address for your account or profile from your server administrator. To test your incoming mailbox 1 In BMC Remedy User, open the AR System Mailbox Configuration form. 2 Search for the name of the incoming mailbox to test. 3 Compare the account you obtained from your server administrator with the account or profile that your incoming mailbox uses. If necessary, change the form entry to match the account you obtained from your administrator. 4 In a third-party client, create an containing a subject line and body content. 5 Send the to the address you verified in step 3. 6 Wait for the amount of time specified in the Polling Interval for the Incoming Mailbox you are testing (see the Basic Configuration tab). 7 Open the AR System Messages form in Search mode. Testing your mailbox configuration 67

68 BMC Remedy Action Request System Select a mailbox name and perform a search. The results table displays the entry corresponding to the message you sent. Figure 3-8 shows an example of an entry. Figure 3-8: Test entry example 9 Double-click the entry to open the form containing the information for that entry. 10 Make sure that the subject line and content in the form are the same as the subject line and content of the test you sent. If they are the same, your test was successful. If your test fails, see Chapter 7, Troubleshooting. 68 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

69 Administering BMC Remedy Engine Configuring security Incoming and outgoing s use different security mechanisms. Incoming messages use security keys, the user s login and password, or the user s address for validation. As long as the has one of the previous security mechanisms, the engine will execute the appropriate action. You can configure the engine to use all three methods. But if the message is performing a modify action, then only a security key will validate the user s request. Outgoing messages, which include the results of query actions, use AR System access control for forms and fields. If a user does not have access to the field or form being queried, the field and its contents will not be included in the outgoing message. The following sections provide instructions for creating security keys for incoming , describe how security is handled for outgoing , and provide instructions for configuring the engine to allow modify actions. Configuring incoming mailbox security Security keys associated with an incoming mailbox validate the permissions for incoming s to perform various actions, such as modifying entries, on the AR System server. In the AR System Mailbox Configuration form, you specified whether a security key is required for sent to a mailbox (see Advanced incoming mailbox configuration on page 61). If you chose to use a security key, you must create the key and associate it with a mailbox in the AR System Security form. When mail arrives, the engine validates the security key included in the incoming message against the information in the AR System Security form. If the key is valid, the engine checks the mailbox owner name in the form. Configuring security 69

70 BMC Remedy Action Request System 7.0 To create security keys 1 In BMC Remedy User, open the AR System Security form in New mode. Figure 3-9: AR System Security form 2 Enter the following information in the fields: a Status Select Enabled to activate the key. b Key Enter a set of alphanumeric characters. Consider the following issues before you enter the characters: Security keys are case-sensitive. For example, CITYSCAPE, Cityscape, and cityscape are all different. Do not use names that are common to your working environment or that could be easy to guess. For example, do not use a favorite product nickname, your name, or a campus building name. Mix numbers, letters, and special characters to make the key more difficult to guess, for example: City2Scape or City!Scape. Do not use spaces, forward slashes, or backslashes. 70 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

71 Administering BMC Remedy Engine c d e f g h i j User Name Enter the name of a valid AR System user to which the security key applies. Force for Mailbox Select Yes to enable the security key for this mailbox only. Enter No to enable the key for all mailboxes in your environment. Mailbox Name Enter the name of the incoming mailbox that the security key applies to. Force from Addresses Select Yes to require this key for s received from specific addresses. Allows the key to work only if it comes from the mailbox contained in the addresses field. Addresses Enter the addresses that the security key should apply to, if you enabled the Force from Addresses key. Expires Select Yes if you want the key to expire on a specific date. If you select Yes, the Expiration Date field becomes enabled. Expiration Date Enter an expiration date for this security key. Once the key expires, you can either modify the expiration date in this form, or set the Expires field to No. Description Enter a description of the key. For example, explain why the key was created or include instructions to modify or delete it. Configuring outgoing mailbox security Outgoing messages, which include the results of query actions, make use of AR System access control for forms and fields. If a user does not have access to the field or form being queried, the field and its contents will not be included in the outgoing message. The server uses the following criteria to define security for outgoing s that contain query results: An sent to only one user will contain data that only the user has permission to view in BMC Remedy User. An sent to more than one user will only contain data that only the user with the most restricted permissions can view in BMC Remedy User. Configuring security 71

72 BMC Remedy Action Request System 7.0 For example, if an is sent to both an administrator with full access permissions and to a user with only Public access, only data allowed by Public access will be included in the . Note: If one of the recipients of an message does not have access to any of the fields used in a query, the message will not be sent because the system does not allow execution of a query on fields for which a user does not have access permission. If a record is locked by the system through the row-level access feature, the record will be included only if all recipients have access to it. If an that includes query results is sent to a nonregistered AR System user, the form and fields queried must have Public access, and the AR System server must be configured to allow guest users. Configuring the engine for replying with results When you set the Reply with Result and Reply with Entry fields on the AR System Mailbox Configuration form to Yes, the engine sends reply back to the sender. The engine formats the data from the form back to the From Address, letting the sender see what was submitted, queried, or modified on the form. To configure the engine for replying with results 1 Log in to BMC Remedy User. 2 Open the AR System Mailbox Configuration form in Search mode. 3 Search for and open the records for your incoming and outgoing mailboxes. 4 Make sure that you have an incoming mailbox and an outgoing mailbox associated with each other. 5 Click the Advanced Configuration tab of the outgoing mailbox. 6 (Recommended for testing purposes) Set the Delete Outgoing Notification Messages field to No. 7 Save your changes. 8 Click the Advanced Configuration tab of the incoming mailbox that you want the modify instruction sent from. 72 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

73 Administering BMC Remedy Engine 9 Set the Action field to Parse. 10 Set the Use Original Template Format field to No. 11 Set the Reply With Result field to Yes. 12 Set the Reply With Entry field to Yes. 13 Set the Enable Modify Actions field to No. 14 Set the Force Default Workflow Form field to No. Note: To use reply with results, make sure that you set one of the following parameters to Yes. 15 Set the Use Security Key field to Yes. 16 Set the Use Supplied User Information field to Yes. 17 Set the Use From Address field to Yes. 18 Save your changes. Configuring the engine for modify actions Modifications are executed by sending a modify instruction or modify action to the engine. Typically, you want only trusted users making changes to records, especially if they are using as a client to the AR System server. For security reasons, incoming with modify instructions do not work by default; you must configure the incoming mailbox to accept modify actions. Important: You must provide a security key for every user who sends modify instructions to the engine. To configure the engine for modify actions 1 Log in to BMC Remedy User. 2 Open the AR System Mailbox Configuration form in Search mode. 3 Search for and open the records for your incoming and outgoing mailboxes. 4 Make sure that you have an incoming mailbox and an outgoing mailbox associated with each other. Configuring security 73

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

75 Administering BMC Remedy Engine 15 Save your changes. Figure 3-10 shows Francie Frontline s security key in the AR System Security form. Figure 3-10: User in AR System Security form Set security key MAPI Saving outgoing notifications If you use the MAPI protocol and you want to save messages on the Exchange server, you must configure your outgoing mailbox to save outgoing notification s in an Outlook folder. To save outgoing notifications, add the following line to the Daemon.properties file: com.remedy.arsys. daemon.<ar_system_server>.mapi_sent_folder=<fol der_name> where: <AR_System-server> is the name of the AR System server associated with the Engine. MAPI Saving outgoing notifications 75

76 BMC Remedy Action Request System 7.0 <folder_name> is the name of the folder that stores the outgoing notification s. Enter Sent Items here to save messages to your Sent Items folder on Outlook. Changing the form entry interval time When the engine starts, it retrieves all the entries in the AR System Mailbox Configuration form and creates incoming and outgoing mailboxes. Every 30 minutes, the engine automatically queries the form for changes to the form entries and updates the information. To enable changes to form entries before the next default query time, stop and restart the engine. To shorten the default time interval in the Daemon.properties file, set the polling parameter. For example, shorten the time to 5 minutes: com.remedy.arsys. daemon.<ar_system_server_name>.interval = 5 For more information about this property or the Daemon.properties file, see Performance and configuration settings on page 236. Configuring SSL for the engine Enterprise and stand-alone certification authorities (CA) can issue certificates for secure using SSL. This section explains in general terms how to configure the Secure Socket Layer (SSL) for use with the engine. There is no One Size Fits All CA solution. You must consider various factors when using SSL, for example, what CA you decide to use. Configuration differs considerably whether you use a commercial CA authority like VeriSign, or you configure a certificate server in a non-active directory environment using Microsoft s Certification Authority management console. Note: Secure Sockets Layer (SSL) is an open standard developed by Netscape Communications for establishing and protecting web communications and preventing the interception of critical information, such as credit card numbers. Figure 3-11 illustrates a digitally signed message that uses SSL. 76 Chapter 3 Configuring mailboxes in the BMC Remedy Engine

77 Administering BMC Remedy Engine Figure 3-11: with digital signature Dig me in e For more information, you can read an excellent description of general CA procedures (for Windows systems) at the following URL: To configure SSL for the engine 1 Set up a local CA or search for a CA to use with your mail server. You must decide whether to use a commercial CA (for example, VeriSign) or use a CA created in-house. Most Windows system administrators can set up a CA on a Windows server in just a few minutes. The primary difference between a commercial or in-house CA is that a cert (certificate) issued by Verisign is trusted far and wide, while a cert issued by an in-house CA is trusted by no one outside the organization. 2 In Exchange System Manager (performed by an Exchange system administrator only), return the properties for the IMAP virtual server. a Use the Certificate Wizard to generate a cert request. b Save it where you can easily access it. Configuring SSL for the engine 77

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

79 Administering BMC Remedy Engine c Two users who have properly configured the certs on their mail client must then exchange certificates so that their communications can be secured. Send messages that are signed, but not encrypted, between the two users. Figure 3-13: Signed Bu sig Outlook Express has large buttons for signing and encrypting messages, as shown in Figure The client should automatically notice the signed message and store the certificate, so that it can be used to encrypt further messages exchanged between the users. Configuring SSL for the engine 79

80 BMC Remedy Action Request System Chapter 3 Configuring mailboxes in the BMC Remedy Engine

81 Chapter 4 Outgoing This chapter provides information and instructions for creating and transmitting outgoing messages from the engine. The following topics are provided: Overview How outgoing works (page 82) Using outgoing (page 84) Using notifications (page 85) Using the Messages form to send outgoing (page 108) Sending reply Giving a professional look to outgoing (page 126) Outgoing 81

82 BMC Remedy Action Request System 7.0 Overview How outgoing works Figure 4-1 presents a sample scenario that demonstrates how the engine sends outgoing notifications. In this scenario, John, the local BMC Remedy administrator, has decided to test the notification capabilities of the BMC Remedy Engine. Figure 4-1: How the engine send outgoing notifications 1 AR System admin defines SLA Engine AR System Server messages To: Abcdefg From: Hijklm Message: Nopqrstuvwxyz Outgoing records 2 Escalation Underlying Database HD Incident Server escalation executes that triggers workflow action Notify 6.3 Engine Field 1 Abcdefg Field 2 Hijklm Field 3 Nopqrst Mail Server Outgoing Mailbox 3 Outgoing is formatted and assembled account 4 User receives urgent ticket assigned to him Bob Backline 82 Chapter 4 Outgoing

83 Administering BMC Remedy Engine Step 1 Step 2 Step 3 Step 4 In the XYZ Company, the IT department has a service-level agreement (SLA) that urgent HD incident tickets must have a response in one hour. The BMC Remedy administrator designs an escalation that triggers a Notify action to send an notification to the backline support engineers if the SLA is not met. Because of a sudden swell of incoming tickets, the front line engineers are swamped and cannot respond to one of the urgent request in one hour. As a result, the AR System server triggers an escalation. Because John has configured the Notify escalation to use as the notification mechanism, when the escalation is triggered, the AR System server creates an outgoing record in the AR System Messages form. The engine monitors the AR System Messages form for all outgoing messages, and then sends the messages to the outgoing mailbox on the mail server. The engine constructs the message according to formatting instructions contained in the Outgoing Mailbox it is using. This message consists of the field values from the HD Incident form (submitter, short description, its urgent status, assignee, and so on). The engine then transmits the message to the mail server with instructions to notify Bob Backline, the back line Customer Support engineer. Bob s client receives the new . He reads that an urgent ticket has been assigned to him. Most importantly, Bob sees that all the necessary details of the ticket are contained in the constructed by the engine. For more information, see the following sections: Configuring outgoing mailboxes on page 53 Defining workflow to send notifications on page 86 Overview How outgoing works 83

84 BMC Remedy Action Request System 7.0 Using outgoing Important: The examples of outgoing in this chapter make extensive use of label/value pairs, aliases, variables, templates, and special keyword syntax as message content; the BMC Remedy Engine ignores any other text. For more information, see the detailed reference material and examples of their use in Chapter 6, Using templates. The sections in this chapter are divided into the three types of outgoing in the BMC Remedy Engine: Notifications The most important use of outgoing is using workflow to send notifications to users. The AR System uses the engine to send all notifications, not just . You must install the engine to send notifications from the AR System server. For more information, see Using notifications on page 85. Replies to senders The next most common function of outgoing is making replies to senders (who send to the incoming mailbox) with results. When you created an incoming mailbox, one crucial task you performed was associating an outgoing mailbox, specifically for the purpose of replying to s that require a response, for example, query results. For more information, see Sending reply Giving a professional look to outgoing on page 126. Messages form You have the ability to send outgoing using the AR System Messages form. You can type the message, or specify contents templates to use in the body of the . Typically, you only use the AR System Messages form for configuring or troubleshooting the engine. The average user will never see or need this form. For more information, see Using the Messages form to send outgoing on page Chapter 4 Outgoing

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

86 BMC Remedy Action Request System 7.0 If you choose as the delivery mechanism when creating a Notify filter or escalation, you can send the following types of information in an notification: Text messages Contents of selected fields provided the user being notified has the appropriate permission for those fields Attachments if an attachment field exists on the form Shortcut if you select the Add Shortcut option in the Notify dialog box, a shortcut will be added as an attachment to the notification. This shortcut provides a link to the entry on the AR System server. To send notifications, you must install the BMC Remedy Engine. The BMC Remedy Engine can be installed on a separate server from the AR System server processing the workflow. When you install BMC Remedy Engine, point to the AR System server you intend to use. For more information about using filter or escalation workflow, see the Form and Application Objects guide. Note: If you create notifications using the Submit execute condition with join forms, the fields returned in the notification message will not be populated. This is because there is no Request ID with join forms during a Submit operation. Defining workflow to send notifications When the filter or escalation is triggered (for example, from a filter submit or modify action, as shown in Figure 4-3), the AR System server will log a message containing the notification text (and field contents these are optional) on the AR System Messages form. The engine then picks up the entries from the form, processes them, and sends the notifications to the designated user (or group). 86 Chapter 4 Outgoing

87 Administering BMC Remedy Engine Figure 4-3: Filter window In a Notify action from filter or escalation workflow (see Figure 4-4 on page 88), you can select as a notification mechanism. When you select , the bottom part of the window displays three tabs Fields, Messages, and Templates that are used to define the configuration and contents of your message. Tip: This section borrows from the Engine: Administering (Webcast) available from BMC Remedy Training. This webcast includes.def and data files you can download and modify for your own use. For more information, see The BMC Remedy Engine must be running to enable you to send notifications. You can set some configuration options in the Create Filter (or escalation) dialog box when you create a Notify filter or escalation to customize your . Using notifications 87

88 BMC Remedy Action Request System 7.0 To define workflow to send 1 Make sure that you have an outgoing mailbox configured with Default Outgoing Mailbox set to Yes or set Mailbox Name in the workflow to the configured outgoing mailbox. Otherwise, you will not receive any notifications. For more information, see Chapter 3, Configuring mailboxes in the BMC Remedy Engine. 2 Create your Notification filter or escalation. 3 Click the If Action tab or the Else Action tab. 4 From the New Action list, select Notify. The Notify Filter (or escalation) page of the Create Filter (or escalation) dialog box is displayed. The fields required to define the Notify filter or escalation appear. Figure 4-4 shows these fields and an example of how a Notify action might look. Figure 4-4: Notify filter or escalation action 88 Chapter 4 Outgoing

89 Administering BMC Remedy Engine 5 In the Text field, enter the text of the message. There is a 32 KB limit to the amount of text you can include in notifications, instead of the 255-character limitation that existed in previous versions of AR System. You can use the Text list to insert fields from the current form or keywords into the text. The field or keyword will be expanded when the notification is sent, to a maximum of 32 KB. You can include sophisticated AR System functionality in the text of an notification. Figure 4-5 demonstrates the use of a direct access URL that performs a search that goes directly to the request the user needs to view. The $Impact$ incident, <a href=" ViewFormServlet?server=polycarp&form=HD+Incident&eid=$Request ID$">$Request ID$</a>, has been assigned to you. This direct access URL appears in the notification as a link that the user clicks to display the ticket in a browser (as shown in Figure 4-2 on page 85). Figure 4-5: Direct access URL used in notification Direct access URL For detailed information about creating and using direct access URLs, see the Form and Application Objects guide. 6 In the User Name field, enter the name of the users or groups to notify. For each recipient, an entry is made in the AR System Messages form (see Figure 4-9 on page 95). You can enter a maximum of 255 characters. To specify one or more recipients, enter any of the following choices separated by hard returns (the server evaluates each line separately) in the User Name field: AR System user logins AR System groups Direct addresses Using notifications 89

90 BMC Remedy Action Request System 7.0 Include the domain name if you are entering a direct address (for example, [email protected]) or a keyword (for example, [email protected]). The order in which these entries appear is the order in which the engine searches for addresses. If the contents of the User Name field do not match an existing User or Group definition, the system interprets the field contents as a literal address and sends the notification to that address by SMTP, IMAP, MAPI, or POP mail protocols. This address can be an address representing users who are not using AR System, an alias for a group, or an address representing a program. WARNING: Do not use group notifications as an system for broadcast type items because the server processes a notification for each member. An alias is more efficient. If you are using a field reference (for example, $Submitter$), do not include the domain name as part of the notification because the address is being read from the Address field of the user s entry in the User form. 7 Enter a value in the Priority field; ranges of 1 to 10 are acceptable. By default, s are sent out from the engine in the order they were received, not in the order of priority. But you can set properties in the Daemon.properties file for the engine to send high priority s first and then lower priority in that order. Use the following properties: To ignore priority (default): com.remedy.arsys. daemon.sortmessages=false To use the priority: com.remedy.arsys. daemon.sortmessages=true For more information about using the Daemon.properties file, see Performance and configuration settings on page From the Mechanism field, select . The Fields, Messages, and Templates tabs become activated. For more information, see Defining fields in notifications on page 91 and Using the Messages and Templates tabs on page Chapter 4 Outgoing

91 Administering BMC Remedy Engine 9 Select the Add Shortcut check box to include the originating request as an ARTask attachment in the that is sent. 10 Save the filter or escalation. Defining fields in notifications You use the Fields tab to define the subject line of the and indicate which fields (if any) to include in the body of the , as shown in Figure 4-6. Figure 4-6: Subject line and fields in notification Subject line of Fields included in To define the Fields tab 1 Enter the text that will appear in the subject line of the . Subject text can include the use of keywords, for example, $USER$. The field or keyword will be expanded when the notification is sent. If you enter a field name in the Subject Line field, the notification will contain the value of the field in the database. You can enter a maximum of 255 characters. 2 Select which fields have the content you want to select in the (in addition to the notification text). Note: The Request ID of entries from display or vendor forms will not be returned in a notification. The system will not generate errors, but also will not return the Request IDs. Using notifications 91

92 BMC Remedy Action Request System 7.0 The options are: None All Selected Changed None of the fields is included with the notification. All of the fields in the request are included with the notification. Selected fields from the fields list are included with the notification. Only fields that have changed in the current transaction are included with the notification. Note: If you use a content template to format the , the template will override any of the options that are selected. For example, if an administrator selected All, but the template only uses a few fields, only the fields in the template appear in the . Make sure that all fields used as variables in header, footer, and content templates are selected in the Include Fields list of the filter. (For more information, see Variables on page 203.) To be able to send the field contents, make sure that users being notified have the necessary permissions. For more information about access control for users, see the Configuring guide; for groups, see the Form and Application Objects guide. The order of fields included in an notification is strictly based upon their arrangement in the form view. Using their X and Y coordinates, the order of fields begins top left to right, then down (in a zigzag-like pattern). Fields excluded from the form s default view are randomly included at the bottom of the list. If a form includes page fields, the pages are ignored. The order of fields included in the notification is still based on their actual X and Y coordinates in the form. 3 To include attachments in an notification, select the attachment fields from the Fields list. 92 Chapter 4 Outgoing

93 Administering BMC Remedy Engine Figure 4-7: Including attachments with notifications Attachment fields you can include in notifications Make sure the receiver of the notification has permission to the attachment field on the AR System form. Figure 4-7 shows that this notification will be sent to the ticket assignee ($Assigned To$). To receive the attachment, the $Assigned To$ group must have permission to the field, which the AR System administrator defines when the field is created. After the notifications are sent, the message status changes in the Messages form from Yes to Sent. If you chose to delete Notification messages in your mailbox configuration, the notification entry is deleted from the BMC Remedy Messages form. (See Deleting notifications on page 104.) Using the Messages and Templates tabs The Messages and Templates tabs allow you to determine at run time which user the came from, which mailbox to use, which templates to use, and so on. The fields in these tabs are optional. If you leave these fields blank, the settings relating to the mailbox entered in the Mailbox Name field apply. Or, if the Mailbox Name field is empty, the default outgoing mailbox settings apply. The default outgoing mailbox is the first mailbox created, or you can specify another mailbox in the AR System Mailbox Configuration form. Any entries in the fields in the Messages and Templates tabs will override the default settings. If there are no entries in the Messages and Templates tabs, and no default mailbox exists, an error message will be generated. Using notifications 93

94 BMC Remedy Action Request System 7.0 Figure 4-8: Notify filter or escalation dialog box Messages tab Defining messages in notifications You use the Messages tab to define your mailbox configuration settings. If you leave these fields blank, the values in your notification default to your current mailbox configuration settings. To define the Messages tab 1 In the Mailbox Name field, enter the name of the outgoing mailbox that you want to handle the notifications if you do not want to use the default mailbox. You can use a field or a keyword to substitute the mailbox name. This mailbox name should correspond to a valid mailbox configured in the AR System Mailbox Configuration form. 2 Enter information in the From, Reply To, CC, and BCC fields: If you make multiple entries in these fields, separate the entries by hard returns. 94 Chapter 4 Outgoing

95 Administering BMC Remedy Engine You can use the following entries in the fields: AR System user logins AR System groups Direct addresses Include the domain name if you are entering a user s name (for example, [email protected]) or a keyword (for example, [email protected]). A field A keyword The order in which these entries appear is the order in which the engine searches for addresses. If you fill in these fields, the BMC Remedy Engine populates the equivalent fields in the AR System Messages form for the appropriate User Name (Figure 4-9). Figure 4-9: AR System Messages form If, however, the information for these fields in the AR System Messages form is supplied from the AR System Mailbox Configuration form (that is, a specified mailbox, or a default mailbox that has already been configured), you need to display and save the AR System Messages form before you see the entries. Using notifications 95

96 BMC Remedy Action Request System In the From field, enter the name to be displayed to indicate where the mail is from. If this field is blank and there are no entries in the From field on the Advanced tab of the AR System Mailbox Configuration form for the specified mailbox, or for the default mailbox, there will be no entry in the to indicate who the is from. 4 In the Reply To field, if you enter a group name, a reply will be sent to all the names in the group. If this field is blank, and there are no entries in the Reply To field on the Advanced tab of the AR System Mailbox Configuration form for the specified mailbox, or for the default mailbox, there will be no entry in the to indicate any Reply To. 5 In the CC and BCC fields, if there are no entries in these fields or the Default Addressing section of the Advanced tab of the AR System Mailbox Configuration form for the specified mailbox, or for the default mailbox, no copies of the will be sent. If you specify multiple recipients in the User Name field (see Figure 4-4 on page 88), the name or names specified in the CC and BCC fields on this form will appear only in the CC and BCC fields of the AR System Messages form entry for the first user listed in this User Name field. The permissions applied to the recipients of the CC and BCC fields will be the same as those of this first listed user. This might be a security issue, especially if you list a group name with some ambiguity about which is the first name on the list. You might list names individually in the User Name field so that you have more control over the permission status. 6 In the Organization field, enter a company name, an organization, a keyword, or a field reference to a name that you would like to appear on the . Defining templates in notifications You use the Templates tab to define any templates to use in the . If you leave these fields blank, the values in your notification default to your current mailbox configuration settings. You could create workflow that substitutes a specially designed urgent template to alert a manager to the s importance. Figure 4-10 illustrates an sent by the engine if an urgent ticket is created and no user is assigned (( 'TR.Impact' = "Urgent") AND ( 'Impact'!= 'DB.Impact') AND ( 'Assigned To' = $NULL$ )). 96 Chapter 4 Outgoing

97 Administering BMC Remedy Engine Figure 4-10: Urgent generated by engine Tip: A more advanced solution can use a Set Fields action to dynamically set template values using data-driven workflow on a transaction basis. For example, a filter could read a value from a hidden field on a form. By default, a notification would use a default header template. But if a ticket was marked urgent, workflow would substitute a value that uses the urgent header template instead. For more information, see Dynamically assigning templates to outgoing on page 99. To define the Templates tab 1 In the Header, Content, and Footer fields, specify the names of the templates to use for a header, content, or footer of the notification. You can enter the name of the template directly, or enter a field reference or keyword that leads indirectly to a template name. The templates specified here must be stored in the AR System Templates form and the name used here must be the same as that entered in the Template Name field of the AR System Templates form. Using notifications 97

98 BMC Remedy Action Request System 7.0 Figure 4-11: Notify filter or escalation dialog box Templates tab For more information about creating and using templates, see Chapter 6, Using templates. When you create a content template for notifications, the variable format must correspond to a field s database name and not the field label. If you want to use a content template for notifications, you must specify it when creating workflow in the Templates tab, in the Notify action for filters and escalations. If you are using a content template for notifications and you want to see the notification text in the corresponding , you must use the following variable format in the content template: #$$AR Notification Text$$# If you want to create a content template to show Status History when doing notifications, the Status History must be represented in the following formats: #$$Status History.New.USER$$# #$$Status History.Closed.TIME$$# 98 Chapter 4 Outgoing

99 Administering BMC Remedy Engine These formats are based on AR System core field ID 7. In addition, the Status History strings shown here as examples could be languages other than English. Note: You cannot use AR System keywords in content templates for outgoing s in notifications. 2 Click Add Action, and save your changes to the filter or escalation. The system determines which templates to use in the following order: a The template entries in this tab. b The templates set as defaults for the mailbox entered in the Mailbox Name field of the Messages tab of the Notify action dialog box. (See Figure 4-8 on page 94.) c The templates set as defaults for the default mailbox. d No templates are used. If no template is used for the Content, the order of fields included in an notification is strictly based upon their arrangement in the form view. Using their X and Y coordinates, the order of fields begins top left to right, then down (in a zigzag pattern). Fields excluded from the form s default view are randomly included at the bottom of the list. If a form includes page fields, the pages are ignored. The order of fields included in the notification is still based on their X and Y coordinates in the form. Dynamically assigning templates to outgoing The BMC Remedy Engine gives developers more control over the content and format of 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 Templates form. The templates stored in this form are then used by the engine to format outgoing . Using notifications 99

100 BMC Remedy Action Request System 7.0 The filter and escalation Notify action integrates with engine templates, allowing dynamic template assignment. With templates stored as data in a form, you can see them using workflow. The Templates tab of the Notify action allows you to assign header, content, and footer templates. As demonstrated in Defining templates in notifications on page 96, you can hard-code these templates by using the template name. You could also dynamically assign templates through workflow. Suppose that the XYZ software company uses four HTML header templates (already stored in the AR System Templates form) to provide a banner at the top of outgoing s that are sent when records are assigned. The templates are designed so that technicians can quickly tell if an incident s impact is urgent, high, medium, or low. The following table shows which header template to use for an incident based on the impact: Impact Urgent High Medium Low Template Name Header_Urgent.htm Header_High.htm Header_Medium.htm Header_Low.htm You can create a data-driven approach to dynamically assign the correct template for the appropriate impact. The following procedure assumes your engine is properly configured, your users have their own mailboxes set up, you have created and stored your templates, and so on. This procedure requires that you first create the following AR System objects. Two regular forms (XYZ Templates and XYZ Incidents) Selection field on templates form Hidden character field on incident form Filter using Set Fields and Notify actions Search menu for template form (optional) 100 Chapter 4 Outgoing

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

102 BMC Remedy Action Request System Create a regular form (for example, XYZ Incidents). 8 Add a hidden character field (for example, Header Template) to the XYZ Incident form (Figure 4-13). This field stores the name of the header template to be used with each incident when it is created or modified. Figure 4-13: Form with hidden fields Hidden fields to store templates 9 Create a filter to set the value for the Header Template field on the XYZ Incident form. a In the Basic tab, select XYZ_Incidents as the form. b Select Submit and Modify as the execute conditions. c Enter 'TR.Impact'!= $NULL$ as the Run If qualification. Here you want the filter to fire on Submit or Modify whenever the value of the Impact field changes (that is, when the filter detects there is a new transaction value in the Impact field). 10 In the If Action tab, create a Set Fields action with the following parameters: a Read the value for the field from the XYZ_Templates form. b Enter 'Impact' = $Impact$ as the Set Fields If qualification. 102 Chapter 4 Outgoing

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

104 BMC Remedy Action Request System 7.0 This sample could be easily enhanced with a content template used specially for urgent tickets. Displaying date/time or numeric values in notifications When the AR System server sends data to a client with a different locale, the format for numeric and date/time data might change to accommodate the client locale. For example, date/time or numeric values stored on the AR System server have a decimal separator, but when this data is relayed to a German client, the decimal separator is displayed as a comma. notifications do not go through this client transition; therefore, the data in the notification is in the same format as that stored on AR System server. This might result in incorrect date/time and numeric values being displayed in a notification to different locales. For more information, see Submitting requests across different time zones on page 260. Deleting notifications Using the AR System Mailbox Configuration form, you can configure your system to automatically delete notification messages from the AR System Messages form after they have been successfully sent. This default setting reduces the number of records stored in your message form. Tip: Most of the time, you will only use the AR System Messages form for troubleshooting the engine. When you first start using the engine, you might not want notifications automatically deleted to make sure they are sent to the expected users, outgoing is formatted correctly, and so on. But after your engine is running correctly, you should automatically delete notifications, unless you are using templates to modify records; otherwise, your server can quickly fill up with notifications. If you configure the system to delete messages automatically, the engine will not permit you to modify records. The engine includes a security feature that checks the outgoing records to verify that incoming with a modify action comes from the same server. 104 Chapter 4 Outgoing

105 To delete notifications Administering BMC Remedy Engine 1 In the AR System Mailbox Configuration form, open the entry of your outgoing mailbox. 2 Click the Advanced Configuration tab. Figure 4-15: Option to delete outgoing notification messages 3 Set the Delete Outgoing Notification Messages field to Yes. 4 Save your changes. For more information about configuring the system, see Advanced outgoing mailbox configuration on page 56. Using templates with outgoing templates can help you with outgoing mail from the engine, for example, with generated from notification actions or escalations. A mail template exported with BMC Remedy Administrator lists all the available field labels you could use, for example, in creating an outgoing . Note: Replies to incoming are not discussed in this section. For information, see Sending reply Giving a professional look to outgoing on page 126. Using notifications 105

106 BMC Remedy Action Request System 7.0 You can use content templates with notifications or escalations to arrange the fields and values of the entry that triggered the notification. Content templates used with notifications or escalations can contain the following information: Plain text Variables For example, the #$$AR Notification Text$$# variable is replaced by the text entered in the Text Field of Notification group in BMC Remedy Administrator. Core fields For example, core fields are replaced with their actual values in the that is sent out. You use the following syntax with core fields: #$$<DatabaseNameOfField>$$# Form fields You can use the fields on the form on which the notification action or escalation is based in content templates. You use the following syntax with form fields: #$$<DatabaseNameOfField>$$# Content templates used with notifications or escalations cannot contain the following information: Keywords Keyword substitution in content templates is not implemented in the 7.0 engine. As a result, $USER$ or $DATABASE$ in content template will not be replaced with actual values. Field IDs Field IDs are not substituted with entry values. As a result, #$$ $$# is incorrect. Instead, you should use #$$Id_Integer$$# where Id_Integer is the database name of the field The following example illustrates a content template for outgoing notifications: #$$AR Notification Text$$# CORE FIELDS: RequestId: #$$Request ID$$# EmployeeName:#$$Name_Char$$# Submitter:#$$Submitter$$# ShortDescr:#$$Short Description$$# LastModifiedBy:#$$Last Modified By$$# Modified Date:#$$Modified Date$$# 106 Chapter 4 Outgoing

107 Administering BMC Remedy Engine Status:#$$Status$$# StatHist-User:#$$Status History.New.USER$$# StatHist-Time:#$$Status History.New.TIME$$# Employee Info General Fields: Employee Name : #$$Name_Char$$# Employee Id: #$$Id_Integer$$# Employee Salary in Decimal : #$$Salary_Decimal$$# Employee Salary in Currency : #$$Salary_Currency$$# Employee Gender : #$$Gender_Dropdown$$# Employee Marital Status : #$$Marital Status_Radio$$# Employee Interests: #$$Interests_Dairy$$# Employee Skills : #$$Skills_CheckBox$$# Employee Vacation Left : #$$Vacation_real$$# PresentOrPermAddChoiceField : #$$PresentOrPermAddChoiceField$$# Joining Details: JoiningDate_Date : #$$JoiningDate_Date$$# JoiningDateTime_DateTime : #$$JoiningDateTime_DateTime$$# Joininig Date_Time : #$$Joininig Date_Time$$# XML outgoing content templates You can specify outgoing content templates in XML format, as shown in the following example: <?xml version="1.0" encoding="utf-8"?> <Root> <NotificationText>#$$AR Notification Text$$#</NotificationText> <RequestID>ReqId: #$$Request ID$$#</RequestID> <Submitter>Sub: #$$Submitter$$#</Submitter> <ShortDescr>SD: #$$Short Description$$#</ShortDescr> <EmpName>Emp Name: #$$name_char$$#</empname> </Root> HTML outgoing content templates You can specify outgoing content templates in HTML format. HTML outgoing content templates can contain graphic images. The following code is an example of HTML outgoing content template that contains a GIF image: <html> <head> <meta http-equiv="content-language" content="en-us"> <meta http-equiv="content-type" content="text/html; charset=windows-1252"> <meta name="generator" content="microsoft FrontPage 4.0"> <meta name="progid" content="frontpage.editor.document"> Using notifications 107

108 BMC Remedy Action Request System 7.0 <title>lighthouse</title> </head> <body> <p><font face="arial Black"> #$$AR Notification Text$$# </font></p> <p><img border="0" src="./images/lighthouse.gif" width="174" height="188"></p> <p><font face="arial Black"><b>Lighthouse</b></font></p> <p><font face="arial Black"> RequestID: #$$Request ID$$# </font></p> <p><font face="arial Black"> EmployeeName:#$$Name_Char$$#</font></p> </body> </html> Using the Messages form to send outgoing You can use the AR System Messages form to send outgoing , as shown in Figure You can type the message, or specify content templates to use in the body of the . To send from the BMC Remedy Engine, you must use a specific label/value pair syntax along with the Action label in the body of the . Figure 4-16: AR System Messages form 108 Chapter 4 Outgoing

109 Administering BMC Remedy Engine You can include attachments with your using the Attachments tab. From the Advanced Options tab, you can use a template, substitute variables, or an alternate attachment as your body content. (For information, see Displaying advanced options for outgoing on page 117.) Sending outgoing in plain text You can use the engine to send outgoing in plain text. Plain text can include the results of queries, submissions, or modifications to entries contained on your AR System server. These s can be formatted using templates that specify the layout of a message in plain text, HTML, or XML. To send outgoing in plain text 1 Open the AR System Messages form in New mode in a web client (as shown in Figure 4-17) or BMC Remedy User. Figure 4-17: AR System Messages form (displayed in browser) Using the Messages form to send outgoing 109

110 BMC Remedy Action Request System 7.0 Tip: To view the AR System Messages form in a browser, use the following syntax: For more information, see the Form and Application Objects guide. 2 From the Mailbox Name menu, select an outgoing mailbox to use for your message. The settings in the AR System Mailbox Configuration form for the specified mailbox will be used, unless overridden by entries in the AR System Messages form. If you leave this field empty, the default outgoing mailbox will be used. (For more information, see Configuring outgoing mailboxes on page 53.) 3 Select Outgoing from the Message Type list. 4 Click the Message tab and fill in the header information. The From, Reply To, Organization, To, CC, and BCC fields will be populated automatically when you enter the mailbox name if they have been configured in the AR System Mailbox Configuration form. You can override these settings here. a In the To field, enter the name of the user you are sending the to. b Enter other information as needed, for example, an organization. 5 Enter a subject line for your in the Subject field. 6 (Optional) Enter a priority number in the Priority field. Use the following to determine what value to use in the message within BMC Remedy to get the desired MS Outlook priority. Numbers from 1 to 100 are acceptable. Engine Priority MS Outlook Priority 0 Normal 1 High importance 2 High importance 3 Normal (default) 4 Low importance Low importance 110 Chapter 4 Outgoing

111 Administering BMC Remedy Engine By default, s are sent out from the engine in the order they were received, not in the order of priority. But you can set properties in the Daemon.properties file for the engine to send high priority s first and then lower priority in that order. Use the following properties: To ignore priority (default): com.remedy.arsys. daemon.sortmessages=false To use the priority: com.remedy.arsys. daemon.sortmessages=true For more information about using the Daemon.properties file, see Performance and configuration settings on page Click the Plain Text Body tab and enter your message text. There are no syntax requirements for typing plain text in your outgoing message. However, any label/value pairs that you include must follow their specific syntax. For more information, see Chapter 6, Using templates. To add an attachment, see Including attachments with outgoing on page 114. To send the with a template other than the default templates for the specified mailbox, see Using the Templates tab on page 117. To add an attachment alternative to be used for the content of your instead of typing content in the body panes, or using a template, see Using the Variable Replacement tab on page Click Send to send the mail from the outgoing mailbox to the user. Sending outgoing in HTML You can use the engine to send outgoing messages in HTML or XML, which can include the results of queries, submissions, or modifications to entries contained on your AR System server. These s can be formatted using templates that specify the layout of a message in plain text, HTML, or XML. Using the Messages form to send outgoing 111

112 BMC Remedy Action Request System 7.0 To send outgoing messages in HTML 1 Open the AR System Messages form in New mode to create an outgoing message. See Using the Messages form to send outgoing on page 108 for sample contents of an outgoing message, especially steps 2 through 6. 2 Click the HTML Body tab. 3 Enter HTML contents, as in the following example: Server: polycarp<br> Login:Francie Frontline<BR> Password <input type="password" name="password" size="15" maxlength="14"> <BR> Key:1234<BR> Action: Modify<BR> Form:TestSecurityForm<BR> Request ID: <BR> Assigned To <input type="text" name="!4!" size="20" value="assignee"> <BR> Short Description <input type="text" name="!8!" size="40" value="enter a short description"> <BR> Status <input type="radio" value="new" name="!7!"/> New <input type="radio" value="assigned" name="!7!" /> Assigned <input type="radio" value="fixed" name="!7!"/> Fixed <input type="radio" value="rejected" name="!7!"/> Rejected <input type="radio" value="closed" name="!7!"/> Closed <BR> In addition to HTML formats, any label/value pairs that you include must follow specific syntax requirements. For more information, see Chapter 6, Using templates. See any standard HTML reference book or reputable online source ( for how to define HTML, especially input type controls. Additional HTML examples are demonstrated in Sending modify instructions in HTML on page Click Send to send the mail from the outgoing mailbox to the user. The engine generates the in Figure Chapter 4 Outgoing

113 Administering BMC Remedy Engine Figure 4-18: Outgoing (HTML format) This outgoing contains the following HTML input features: Password control field Users become nervous about sending passwords in clear text. For security, this HTML message includes a Password control field as an input type. When the user enters their password, the text is masked; asterisks appear instead of the typed symbols or letters, as shown in Figure Figure 4-19: Password field with encryption Text input fields Users modify the contents of the Assigned To and Short Description fields by using text input fields. Radio buttons Users modify the status by selecting an input type Radio control field. They can select only one radio button option. Using the Messages form to send outgoing 113

114 BMC Remedy Action Request System 7.0 Including attachments with outgoing Attachments are sent with an using the AR System Messages form and the AR System Attachments form. The AR System Attachments form (see Figure 4-21 on page 115) stores attachments for incoming and outgoing s. It also stores attachments for templates, such as a graphic for an HTML template. The system associates the attachment with a specific in the AR System Association form. To add attachments to your 1 In the AR System Messages form, click the Attachments tab (Figure 4-20). Figure 4-20: AR System Messages form Attachments tab 2 Click Add Attachment to open the AR System Attachments form (Figure 4-21). 114 Chapter 4 Outgoing

115 Administering BMC Remedy Engine Figure 4-21: AR System Attachments form Attachment pool 3 Select from the Type list. 4 Right-click in the attachment pool and choose Add from the menu. The Add Attachment dialog box appears. 5 Browse to the file you want to add and select it. 6 Click Open. The file is added to the list of attachments. If you are using a Windows system, you can also drag and drop a file into the attachment pool. 7 Enter a name for the Attachment in the Attachment Name field. If you do not specify a name, the system will see the attachment by its file name and location. To change the name: a Select the item in the attachment pool, and click the edit button in the Attachment Name field. The name of the attachment is displayed in the Attachment Name field. For example: template_attachment1.htm. b Edit the file name as needed, for example, to template1.htm. 8 Click Save. Your attachment is added to the list in the AR System Messages form, Attachments tab. You can right-click in the attachment pool field to select from the context list. You can add an attachment that you have previously saved with the AR System Attachments form by using the following procedure. Using the Messages form to send outgoing 115

116 BMC Remedy Action Request System 7.0 To add previously saved attachments to 1 In the Attachments tab of the AR System Messages form, click the arrow next to the blank field at the bottom of the pane. 2 Select the attachment. 3 Click the Add Existing button. Your attachment is added to the list in the attachment pool. When you send or save your , the and the attachment are associated through the AR System Association form. The system will assign the association a unique ID. Modifying an attachment Use the following procedure to modify attachments in outgoing . To modify attachments 1 Click the Attachments tab in the AR System Messages form. 2 Select the attachment you want to modify. 3 Click the Modify Attachment button to open the AR System Attachments form. 4 Click Search to locate the attachment. The attachment appears on the attachment list. 5 Modify the attachment as required. You can also modify the Attachment Name. 6 Click Save to save your modification. Deleting an attachment Use the following procedure to delete attachments in outgoing . To delete attachments 1 Click the Attachments tab in the AR System Messages form. 2 Select the attachment you want to delete. 3 Click Delete Attachment to open the AR System Association form. 4 Close this form. 116 Chapter 4 Outgoing

117 Administering BMC Remedy Engine 5 Click the Refresh Table button to refresh the table in the Attachments tab of the AR System Messages form. The attachment is deleted from the list. Displaying advanced options for outgoing For outgoing messages, you can include advanced options like replacing variables. You can also view information and errors of the outgoing message. To display the Advanced Options, Message Information, and Errors tabs, perform the following tasks: To display advanced options 1 Create an outgoing message. 2 Select Yes in the Display Advanced Options field of the AR System Message form. 3 Select one of the advanced option tabs: Advanced Options, Message Information, or Errors. Advanced Options tab The Advanced Options tab lets you replace templates, add variables, or use alternative attachments. Using the Templates tab The Templates tab enables you to include a content, header, or footer template with your outgoing Content templates replace the body of the so that you do not have to enter anything in the body tab of the AR System Message form. The content can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. You can create these templates in a text editor, or export them using BMC Remedy Administrator, selecting the form and the fields to be contained in the template. Using the template, you can also specify actions to be performed when the engine parses contents of the . The content template can also contain formatting instructions. Using the Messages form to send outgoing 117

118 BMC Remedy Action Request System 7.0 Header and footer templates are often used to place lines of text or graphics on an outgoing message. If header and footer templates are specified in content templates as a label/value pair, they will be applied to the reply. All the templates you use here must be previously stored in the AR System Templates form. If you leave these fields blank, the system uses the default templates for the specified mailbox in the Mailbox Name field, or it uses the default mailbox and its settings if there is no Mailbox Name entered. The template specified here will override those configured for the specified mailbox, or the default mailbox. See Configuring outgoing mailboxes on page 53 for information about configuring your outgoing mailbox. Adding templates to outgoing Use the following procedure to add templates to outgoing . To add templates to outgoing 1 In the outgoing message, display the advanced options and click the Advanced Options tab. 2 Click the Templates tab. 3 Select templates from the relevant menu lists, or enter the name of a template as defined in the AR System Templates form (Figure 4-22). 118 Chapter 4 Outgoing

119 Administering BMC Remedy Engine Figure 4-22: AR System Messages form Advanced Options, Templates tab Using the Variable Replacement tab The Variable Replacement tab (Figure 4-23) enables you to replace any of the variables in the template with a value at the time of execution. This applies only to the specific outgoing and the templates specified in the Templates tab. Using the Messages form to send outgoing 119

120 BMC Remedy Action Request System 7.0 Figure 4-23: AR System Messages form Advanced Options, Variable Replacement tab (displayed in browser) You can use the Field Values field or the Qualification field with a particular form to retrieve required data and substitute it in the . To replace a field value using a variable replacement 1 Create an outgoing message. 2 Fill in header information. 3 Display the advanced options and click the Advanced Options tab. 4 Click the Templates tab. 5 Select a content template. For example, this content template (which modifies an entry) uses the following label/value pairs: Server: polycarp Login: Password: Key: Action: Modify Form: TestSecurityForm 120 Chapter 4 Outgoing

121 Administering BMC Remedy Engine Request ID: [$$#$$Request ID$$#$$] Submitter!2!: Short description!8!: This template includes a variable value for the Request ID field by replacing the Request ID: label/value pair with Request ID:[$$#$$Request ID$$#$$]. 6 Click the Variable Replacement tab. 7 Enter a value for a variable in the template in the Field Values field, as shown in Figure For example, with the following variable in your template: Short Description!8!: #$$Short Description$$# you would enter in the Field Values field:!short Description!: Create entry for new hire. This value will then be substituted for the variable when the outgoing is sent. When an entry is created in the Messages form for the outgoing message, the Field Values field of the Variable Replacement tab is populated with the database name of the field and its value in the entry. This database name is matched with the database name that is specified within #$$ $$# in the content template, and a substitution is made accordingly. So, make sure to use the exact database name in content template delimited by #$$ $$#. If you create an outgoing from the Messages form instead of using a notification or escalation, then you can use the field ID in the Field Values field of the Variable Replacement tab. In the same tab, you can specify the form name and qualification criteria. As a result, when the outgoing is sent, the qualification criteria is evaluated, entries that match the criteria are retrieved, and the values of the entries are substituted for the field IDs in the Field Values field. If a template is specified in the Templates tab and the template contains field IDs, then those field IDs are substituted with the values of field IDs in the field value of the Variable Replacement tab of the Messages form. 8 Enter the name of the server on which the form resides. 9 Enter the name of the AR System form to which these values apply. 10 Enter any access information necessary in the AR System Server TCP Port field and the AR System Server RPC Number field. Using the Messages form to send outgoing 121

122 BMC Remedy Action Request System Enter a qualification in the Qualification field to search for the Request ID of a record on which you want to perform an action (Figure 4-24). This action will be specified in a Content template. Figure 4-24: AR System Messages form Advanced Options, Variable Replacement tab (displayed in browser) 12 Send the outgoing . The engine searches the specified form for the record, and then it substitutes the Request ID parameter in the Content template with the Request ID value ( ) found with the query (Figure 4-25). 122 Chapter 4 Outgoing

123 Administering BMC Remedy Engine Figure 4-25: with qualification replaced You can also make this static in the Content template by specifying Request ID: instead of the variable Request ID: [$$#$$Request ID$$#$$], but using the Variable Replacement feature allows more flexibility. Using the Messages form to send outgoing 123

124 BMC Remedy Action Request System 7.0 Using the Attachment Alternatives tab The Attachment Alternatives tab enables you to add the content of your as an attachment, instead of typing it into the Body field in the Message tab. You can use plain text or HTML. The contents of the attachment appear in the body of the . You can also add variable values in the form of an attachment file, instead of entering them in the Variable Replacement tab, or send another (stored in.eml format) as an alternative attachment, and the contents of that attached will form the body of the outgoing message. Figure 4-26: AR System Messages form Advanced Options, Attachment Alternatives Attachment field (for example, HTML) Attachment pool To add an attachment alternative 1 Create an outgoing message. 2 Fill in header information. 3 Display the advanced options and click the Advanced Options tab. 4 Click the Attachment Alternatives tab. 124 Chapter 4 Outgoing

125 Administering BMC Remedy Engine 5 In the attachment pool, do the perform the following tasks: a Right-click an attachment field corresponding to the contents of the attachment, as shown in Figure b Select Add to open the Add Attachment dialog box. c Select a file. 6 Select an encoding for the attachment or leave the field empty to use the system default. The system needs to be able to read and parse the contents of these attachments when it creates the outgoing . You can attach only one of each type of alternative attachment to a message form. These attachments are stored as part of the message in the message form. 7 Send the outgoing . Message Information tab The Message Information tab records status information about the , such as the Message ID, the dates sent and received, and if there is any delay in sending the message. Errors tab The Errors tab enables users to view error messages if an is not sent correctly. For example, if the To field has an invalid character like a space, then an error is generated and is viewable in the Error tab. Determining message content of outgoing When sending an message, the message content is determined according to the following sequence: Step 1 If you supply a template, the system uses it as the message body, and uses the following rules for variables: If you supply an attachment in the Values attachment field of the Attachment Alternatives tab of the AR System Messages form, the attachment will be used to determine the values for variables contained in the template. Using the Messages form to send outgoing 125

126 BMC Remedy Action Request System 7.0 If you do not supply an attachment in the Values attachment field, but supply information in the Field Values or a qualification in the Qualification field of the Variable Replacement tab of the AR System Messages form, the information will be used to determine values for variables contained in the template. If you do not supply field values, but your content template contains a query to obtain information to substitute in the , the query information will be used to generate the message. For query information to be used, a form, server, and qualification must be supplied. If any one of these items is missing, the message creation will fail. Note: In terms of performance, a query against another server is more expensive than a query against the current server. If you are going to send many s based on information queried from another server, you should set up an system on another server. If none of these points is true, the system uses the template as is. Step 2 Step 3 If you do not supply a template, but attach a file (HTML or plain text, or both) to the Content attachment fields in the Attachment Alternatives tab of the AR System Messages form, the system uses these attachments as the content. If none of the items in the previous steps is supplied, the system uses the contents of the Body fields in the Message tab of the AR System Messages form for the body of the (HTML or plain text, or both). Sending reply Giving a professional look to outgoing One of the major benefits of the BMC Remedy Engine is the ability to send intuitive, user-friendly messages that are professional looking. messages consist of header, content, result, and (optionally) footer components. Each component can be text or HTML. Usually, header and footer templates are used as defaults in the outgoing mailbox, and content templates are used in outgoing messages or filter notifications. 126 Chapter 4 Outgoing

127 Administering BMC Remedy Engine Imagine a user sends an incoming to search for all urgent open tickets. Without the use of header or content templates, the engine returns the following reply Figure 4-27: Reply in ASCII format This is a simple ASCII-format message generated by the BMC Remedy Engine. It is functional but quite plain. Figure 4-28 shows the same outgoing generated by the BMC Remedy Engine, but this time configured to use an HTML header template and an HTML result template when replying. Sending reply Giving a professional look to outgoing 127

128 BMC Remedy Action Request System 7.0 Figure 4-28: Reply with HTML templates The difference between the two outgoing s is evident. The ASCII contains all the important details, but is plain. Using HTML templates, outgoing conveys the same information but is much more inviting to read. Note: Although most mail clients can display HTML, there might be some clients that cannot display HTML. You need to assess which mail clients are supported in your organization before implementing a pure HTML solution. 128 Chapter 4 Outgoing

129 Administering BMC Remedy Engine Using header templates as a banner with outgoing Adding a header to outgoing messages can enrich the user experience. With a basic knowledge of HTML, you can make your messages look professional. Adding a header requires creating a template, and then configuring the outgoing mailbox to use the new default header template. Note: To add a footer template, you would use the same steps as described in the following procedure. To add a header template 1 Create a header image for the banner in your outgoing message. 2 Create an HTML header file (header_default.html) that contains the rug.gif bitmap. The following is a sample HTML header file that includes the bitmap: <html> <head> <title>default Header</title> </head> <body> <table width="816" bgcolor="#99cc00"> <tr> <td valign="top" width="196"><img src="rug.gif" width="200" height="90" lowsrc="rug.gif"></td> <td valign="top" width="608"> <div align="center"> <p> </p> <p><b><font face="geneva, Arial, Helvetica, san-serif" size="4">7.0 Engine Demo </font></b></p> </div> </td> </tr> </table><hr> </body> </html> This HTML code creates the following header: Sending reply Giving a professional look to outgoing 129

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

131 Administering BMC Remedy Engine Figure 4-30: Outgoing message with header template Using HTML result templates with outgoing If you do not specify a result template for reply , the 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 action, you can easily create a result template in a text editor. The following result template is a simple example that formats the returned text with field variables: XYZ Corporation #$$Submitter$$# has successfully created a #$$Status$$# ticket. Ticket Number: #$$Request ID$$# #$$Assigned To$$# has been assigned to your request. Problem Description: #$$Short Description$$# Using an HTML result template (as shown in Figure 4-31) gives you greater control over the appearance of the returned data and makes the return look much more professional. Sending reply Giving a professional look to outgoing 131

132 BMC Remedy Action Request System 7.0 For more information about data formats and labels, field variables, and result templates, see Chapter 6, Using templates. The following example walks you through the procedure for using result templates with outgoing . The example is simple but complete, and you can easily add more functionality. To use HTML result templates with outgoing 1 Make sure the engine is properly configured to send reply results. For more information, see Configuring the engine for replying with results on page Create a result template for your reply . Figure 4-31 is an HTML result template designed for this exercise. The fields that are referenced in the result correspond to fields used in the HD Incident form. The variables for field values must use the field name (its database name) as the variable name, not the field ID. Figure 4-31: HTML result template 3 Create an entry in the AR System Templates form for your result template. For more information, see Adding attachments to HTML templates on page Chapter 4 Outgoing

133 Administering BMC Remedy Engine 4 Export an template from the HD Incident form. For more information, see Exporting mail templates on page Create a new in your client and address the to the BMC Remedy inbox account. 6 Copy and paste the contents of the exported template into the new , and then fill out the required information for the template. 7 Add the result template parameter to the , and then make sure you filled in all the required fields. Your should look like the following example: # # File exported Tue Sep 28 17:01: # Schema: HD Incident Server: POLYCARP.eng.remedy.com Login: Demo Password: Action: Submit Result: Results Template Default # Values: Submit, Query Format: Short # Values: Short, Full Last Name+! !: Stamps First Name! !: Ivan Location! !: Sunnyvale Address! !: [email protected] Phone! !: Category! !: Networking Type! !: VPN Item! !: Cisco Problem Summary! 8!: Need to install VPN Client. Status! 7!: New # Values: New, Assigned, WIP, Resolved, Closed Submitter! 2!: $USER$ Impact! !: Low # Values: Low, Medium, High, Urgent 8 Send the to the incoming mailbox. If you properly configured the engine and included all the required fields and the result template in your , you should receive a reply (as shown in Figure 4-32) that includes the results of your submission. Sending reply Giving a professional look to outgoing 133

134 BMC Remedy Action Request System 7.0 Figure 4-32: Reply with results For more information, see Creating an reply using result templates in HTML format on page Chapter 4 Outgoing

135 Using XML result templates with outgoing Administering BMC Remedy Engine You can use XML when creating templates for outgoing . The following example uses XML format when creating a result template. The results from a query are returned in XML. To use XML with outgoing 1 Create a template file (for example, result_employee.xml) using XML format: <?xml version="1.0" encoding="utf-8"?> <Employee name="#$$employee Name$$#"> <age>#$$age$$#</age> <salary>#$$salary$$#</salary> <address> <street>#$$street$$#</street> <city>#$$city$$#</city> <state>#$$state$$#</state> <zip>#$$zip$$#</zip> </address> </Employee> This simple example contains an XML attribute (name), an attribute value (#$$Employee Name$$#), and several elements (age) with their values (#$$Age$$#). Tip: You can easily validate your XML file by displaying it in a browser. 2 Add the template as a text template to the AR System Template form. The name of this XML template is employee. For information, see Storing templates in the AR System Templates form on page Send an incoming to the engine that queries the server and returns the results using the XML template, for example: Action:Query User: Demo Server:polycarp Schema:employee Result Template:employee Employee Name! !:John Doe This specifies that the employee XML template be used in the outgoing to return the results of the query. Figure 4-33 displays the outgoing generated by the BMC Remedy Engine. Sending reply Giving a professional look to outgoing 135

136 BMC Remedy Action Request System 7.0 Figure 4-33: Reply from engine using XML template Observe how the query results of this are displayed in XML format. If your outgoing mailbox is configured to include an HTML header, the resulting (combining an HTML header template with an XML result template) would no longer be displayed in purely XML format. 136 Chapter 4 Outgoing

137 Using HTML content templates with outgoing Administering BMC Remedy Engine Rather than entering raw HTML into your outgoing , you can create HTML templates to include content similar to header templates. For example, if you need to send a questionnaire seeking input from users, you can include HTML fields in the message so that users can enter input using text boxes, radio buttons, and so on, instead of as plain text. To add content to an outgoing message 1 Create an HTML template that you will include in your outgoing message. The following sample HTML template defines font styles and colors in the <BODY> tag. You can include embedded styles in your content file, but the BMC Remedy Engine does not support linking your HTML template to a cascading style sheet. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> <TITLE>Remedy/BMC Picnic</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#FF0000" VLINK="#800000" ALINK="#FF00FF" BACKGROUND="?"> <i><font color=# face="arial, Helvetica"> <h1>remedy/bmc Company Picnic</ h1></font></i><hr> <i><font color=# face="arial, Helvetica"><h3>Are you coming to the Remedy/BMC company picnic? <input type=radio name="f7">yes</radio> <input type=radio name="f7">no</radio></font></i><br/> <i><font color=# face="arial, Helvetica">Number of additional guests <input type=text name="num_guests" size=2></font></i></input> </BODY> </html> 2 Create an entry in the AR System Templates form for your content template, for example, Remedy_Picnic_Invite.html. For more information, see Adding attachments to HTML templates on page Open the outgoing mailbox entry in the AR System Mailbox Configuration form. 4 Under the Advanced Configuration tab, specify Remedy_Picnic_Invite.html as the content template. Sending reply Giving a professional look to outgoing 137

138 BMC Remedy Action Request System (Optional) Include a header or footer template. Otherwise, your will use any default templates configured for your outgoing mailbox. 6 Send a sample outgoing . Figure 4-34 displays the outgoing sent by the BMC Remedy Engine to your mail client. Figure 4-34: Outgoing message with header and HTML content templates Using status templates with outgoing When an error occurs while executing instructions from an incoming , the BMC Remedy Engine automatically generates an outgoing with relevant status information. This system-generated is simple, containing only basic information, for example, the type of instruction that failed, error messages, and so on: Instruction: Query Instruction Number: 1 Instruction Template: Message Type: Message Number: Chapter 4 Outgoing

139 Administering BMC Remedy Engine Message Text: No matching requests (or no permission to requests) for qualification criteria. Appended Text: TestSecurityForm By using an HTML status template, your outgoing can be more professional-looking as well. The following procedure shows you how to create an HTML template that will format status in a more attractive format, as shown in Figure To include status templates with outgoing 1 Create a status template. The following is a sample HTML template created to display status: <html> <head> <title>status Template</title> <meta http-equiv="content-type" content="text/html; charset=iso "> </head> <body bgcolor="#ffffff" text="#000000"> <table width="75%" border="1" cellspacing="1" cellpadding="3"> <tr> <td colspan="4"> <div align="center"><b>your request to the AR Server returned the following error. If you have questions, contact your <a href="mail%20to:%[email protected]">administrator</a>.</b></ div> </td> </tr> <tr> <td width="12%">error Number</td> <td width="28%">#$$actionstatus.number$$#</td> <td width="18%">message 1</td> <td width="42%">#$$actionstatus.text$$#</td> </tr> <tr> <td width="12%">error Type</td> <td width="28%">#$$actionstatus.type$$#</td> <td width="18%">message 2</td> <td width="42%">#$$actionstatus.appendedtext$$#</td> </tr> </table> </body> </html> This HTML template defines a simple table with two rows for the error number and error types. It also includes an address that users can respond to if they have questions. Of course, your HTML template could include color, special fonts, and so on. Sending reply Giving a professional look to outgoing 139

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

141 Chapter 5 Incoming This chapter provides information and instructions for sending messages to the AR System server using the engine. The following topics are provided: Overview How incoming works (page 142) Using incoming (page 143) Sending a query instruction to the engine (page 144) Sending a submit instruction to the engine (page 150) Sending a modify instruction to the engine (page 154) Overview Using workflow to modify requests (page 166) Searching for an entry to modify Advanced solution (page 174) Using variables with templates (page 177) Displaying advanced options for incoming (page 178) Incoming 141

142 BMC Remedy Action Request System 7.0 Overview How incoming works Figure 5-1 presents a sample scenario that demonstrates how the engine receives incoming . Figure 5-1: How the engine receives incoming AR System Server AR configured System incoming admin mailbox engine. in 1 4 Server ticket. creates HD Incident Underlying Database 6.3 Engine Printer Broken Abcd ef ghijkl mno Incoming Mailbox Engine 3 instructions. engine Instructions parses calls then translated to server. into API account Mail Server "Printer broken!" 2 Submit sent to incoming mailbox. Joe User 142 Chapter 5 Incoming

143 Administering BMC Remedy Engine Step 1 Step 2 Step 3 Step 4 In the XYZ Company, the BMC Remedy administrator has configured the BMC Remedy Engine to receive submissions using as a client to the AR System server. To make easier to use, he has created and sent to his user base several templates that cover typical work situations, for example, submitting entries to the HD Incident form, querying the status of their tickets, and so on. Joe User cannot print his document because his favorite printer has a paper jam that he cannot fix. Rather than opening BMC Remedy User, he opens one of the templates and sends an to submit a request to the HD Incident form. The engine receives the from the mail server. It parses the instructions in his , and makes the appropriate API calls to the AR System server. The server creates an entry in the HD Incident form. Slightly suspicious of using to create trouble tickets and also wanting to verify the status of his printer problem, Joe User opens the HD Incident form in BMC Remedy User. He is pleasantly surprised to find his entry, already assigned to the frontline Customer Support engineer who is fixing the printer. Using incoming For more information, see Sending a submit instruction to the engine on page sent to the 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 engine. You can give different values to the labels. Using label/value pairs in templates on page 191 provides a table of labels that you can use to send incoming to the engine. Important: The examples of incoming in this chapter make extensive use of label/value pairs, aliases, variables, templates, and special keyword syntax as message content; the BMC Remedy Engine ignores any other text. For more information, see the detailed reference material and examples of their use in Chapter 6, Using templates. Using incoming 143

144 BMC Remedy Action Request System 7.0 Using incoming , users can submit, query, or modify entries on the AR System server. Users can send incoming s through an external client to a configured mailbox on the engine. If users send through a third-party client, they can either enter the content into the body of the or they can specify a template. The message content of incoming 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: Action: Submit The rules for label/value pairs and variables are exactly the same as those for templates. Tip: Like BMC Remedy User, incoming can trigger workflow that fire on submit or modify. functions like any other BMC Remedy client to the AR System. For example, if the transaction meets the filter s Run If condition, the filter will fire, regardless of whether the client is BMC Remedy User or an . Sending a query instruction to the engine The easiest way to send queries to the engine is to think of as simply another client of the AR System, like BMC Remedy User. When performing queries with BMC Remedy User, users must perform certain basic actions, for example, logging in, opening a form, and then performing a query. Using as an AR System client is no different. To execute query instructions to the engine, the following information must be included: AR System server name AR System Login and Password to authenticate a user Form name on which to execute the instruction Query action 144 Chapter 5 Incoming

145 Administering BMC Remedy Engine The major difference between BMC Remedy User and an client is that BMC Remedy User sends its queries directly to the AR System server, while incoming is first processed by the engine and then sent to the server. To send a query 1 Create a new message in your mail tool. 2 Address the 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 message to the engine: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Query Tip: Copy and paste these examples into your mail client, and then modify them as needed. Figure 5-2 shows the minimum of information you need to send a query . Here a label called Action specifies an instruction. To send a query to the engine, the label Action must be set to Query. Figure 5-2: Query instruction Sending a query instruction to the engine 145

146 BMC Remedy Action Request System Send your . 5 (Optional) Use the AR System Messages form to verify that the engine has received your . Figure 5-3: Incoming received and outgoing mail sent After the engine has parsed the instruction and sent the query to the AR System server, the server returns the query results that the engine sends back to the client (as shown in Figure 5-4). Otherwise, the engine will return an error message that indicates missing parameters or an error while parsing the qualifier. 6 Open the returned to see the results of your query (Figure 5-4). 146 Chapter 5 Incoming

147 Administering BMC Remedy Engine Figure 5-4: Results returned Tip: One benefit of the BMC Remedy Engine is that outgoing from the engine can include a formatted header or footer, like the HTML header template shown in Figure 5-4. For more information, see Incoming and outgoing mail templates on page 185. This message sent from the engine shows that all fields of all entries in the HD Incident form were returned. In effect, your query was an unqualified search of the HD Incident form, useful for our example, but certainly a performance impact on the server. You should always include a qualification in your queries. Sending a query instruction to the engine 147

148 BMC Remedy Action Request System 7.0 Including qualifications in your You can limit the entries returned by a query by using a label called Qualification. The syntax of the value given to the qualification is the same as what is used in the Advanced Search Bar in BMC Remedy User. As a result, any search that executes in the Advanced Search Bar in BMC Remedy User will also work with the Qualification label. Tip: Create a user-defined instruction that runs the query. This allows the user to quickly execute queries based on instructions that the administrator has predefined. To include qualifications in an incoming message 1 Create an . 2 To execute a query that returns all tickets submitted by Francie Frontline, include the Qualification label with the following query value in your message to the engine: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Query Qualification: 'Submitter' = "Francie Frontline" This query returns all fields of all records that were submitted by Francie Frontline. In the qualification, the field name Submitter must be the same as the database name of the field. Also, field names are case sensitive, and must exactly match the database name of the field. You can also query entries using field IDs instead of the database name of the field. For example, the following Qualification label will produce the same results when the Submitter field has a field ID equal to 2. Qualification: '2' = "Francie Frontline" In your qualification, you can also include relational operators. The following qualification retrieves an entry whose employee ID = 9 and that was submitted by Francie Frontline. Qualification: 'Employee_Id' = 9 AND 'Submitter' = "Francie Frontline" 148 Chapter 5 Incoming

149 Administering BMC Remedy Engine Using shorthand qualification syntax Like BMC Remedy User, which allows you to enter criteria into form fields themselves (without entering them into the Advanced Search Bar), the engine supports a shorthand syntax of qualification criteria. For example, when the Submitter field has a field ID equal to 2, the following syntax produces exactly the same results as if you had entered Francie Frontline in the Submitter field in BMC Remedy User:!2!: Francie Frontline You can use this same shorthand syntax to search for request IDs. The following template searches for request ID from the HD Incident form: Schema: HD Incident Server: polycarp Login: Demo Password: Action: Query!1!:TT Using the Format label Your query can include multiple fields to search for all new urgent requests: File exported Tue May 21 21:38: Schema: HD Incident Server: polycarp Login: Demo Password: Action: Query Status!7!: New Caller Impact! !: Urgent If the qualification does not match any entries, the returned from the engine will indicate this. Observe that the confirmation sent from the outgoing mailbox (Figure 5-4 on page 147) listed all the fields of the form. This is the default behavior of query instructions. You could use the Format label to send an query instruction that includes only the fields specified in the results list of a form, just like the results you would see in BMC Remedy User. Sending a query instruction to the engine 149

150 BMC Remedy Action Request System 7.0 To use the Format label 1 Create an . 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 message to the engine: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Query Format: Short If the Format is not explicitly specified, by default, it will be automatically assigned a value of Full, which will return all fields in the form. Sending a submit instruction to the engine Like BMC Remedy User, you can use as a client of the AR System to submit entries on the server. To submit an entry into an AR System form, send an with instructions with the Action label set to Submit. To execute submit instructions to the engine, the following information must be included: AR System server name AR System Login and Password to authenticate a user Form name on which to execute the instruction Submit action Any mandatory fields To use the Submit action label in an incoming 1 Create a new message in your mail tool. 2 Address the message to the incoming mailbox. 150 Chapter 5 Incoming

151 Administering BMC Remedy Engine 3 To execute a submit action that creates an entry that contains the text Printer not working in the Short Description field of the HD Incident form, enter the following information in your message to the engine: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Submit!Submitter!: Francie Frontline!Short Description!: Printer not working The field name between the exclamation marks must exactly match the field name in the database and is case sensitive. As with a Query action, Submit actions can also use the field ID instead of the database field name. The following syntax will return the same results if the Short Description field ID equals 8:!8!: Printer not working You can add a comment before the exclamation mark used with field names as in the following example. The engine will parse only the characters between the exclamation marks, for example, the field ID (8) of the Short Description field: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Submit What is the problem!8!: Printer not working Who is submitting!2!: Francie Frontline If the value for the field is more than one line, then enclose it between [$$ and $$]. For example, if you have a longer value for the Short Description, it could be sent to the engine as:! Short Description!: [$$This is a longer description which spans multiple lines, so use this syntax.$$] The engine will correctly parse the syntax when the is submitted. 4 Send your . If you successfully submitted your , the returned will look something like this: Instruction 1 has successfully created a new record with Request ID : Sending a submit instruction to the engine 151

152 BMC Remedy Action Request System 7.0 If the incoming mailbox is configured to Reply With Entry, then all the fields of the newly created entry will be returned to the sender. (For more information about this configuration option, see Advanced incoming mailbox configuration on page 61.) If the entry cannot be created, the engine will return an error message (as shown in Figure 5-5) that indicates missing parameters. Make sure your incoming includes all required fields, for example, Submitter. Figure 5-5: Error message reply from engine Tip: Another benefit of the engine is that status from the engine can be formatted, like the status template shown in Figure 5-5. For more information, see Incoming and outgoing mail templates on page Chapter 5 Incoming

153 Administering BMC Remedy Engine Using keywords You can use keywords such as $USER$ to supply the actual value for the field. Instead of specifying a text value, you can use keywords, as the following example shows: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Submit!Submitter!: $USER$!Short Description!: Printer not working Using the Format label Like the Query instruction, you can use the Format label to specify if you want your confirmation from a Submit instruction to include all fields from the form or only those fields in the results list. To use the Format label, you must configure the incoming mailbox Reply With Entry parameter to Yes. If Reply With Entry is set to No, then the Format label is ignored and the confirmation will contain only the Request ID number. Note: Join forms do not send values of fields on Submit when the Reply with Entry parameter is set to Yes for the incoming mailbox. By default, the Format label is set to Full, which means all fields in the form are included in the confirmation . If you want the confirmation message to include only fields from the results list, then set the Format label to Short: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Submit Format: Short!Submitter!: Francie Frontline!Short Description!: Create entry for new hire. Sending a submit instruction to the engine 153

154 BMC Remedy Action Request System 7.0 Including attachments with incoming Submit instructions can also include attachments. To include attachments 1 Create a new message in your mail tool. 2 Address the message to the incoming mailbox. 3 To include an attachment in an , use the attachment field name or field ID: Schema: HD Incident Server: polycarp Login: Francie Frontline Password: <mypassword> Action: Submit!Submitter!: Francie Frontline!Short Description!: I am including the filter.log file. Attachment field! !: filter.log Your label/value pair syntax should not see the attachment pool, but to specific attachment fields. 4 Insert your attachment file anywhere in the . If the attachment name including the extension is not supplied, the submission will not pass the attachment to the attachment field. Do not include two attachment files with the same name, as in the following example: Attachment field 1! !: filter.log Attachment field 2! !: filter.log The engine will accept the submit instruction; however, the engine is unable to recognize which of the two filter.log files to insert into the attachment field. Sending a modify instruction to the engine Sending a modify instruction to the engine is more complicated than sending query or submit instructions. To allow users to modify an entry, you must configure the BMC Remedy Engine to accept modification requests. Do not delete outgoing notifications with modify instructions. 154 Chapter 5 Incoming

155 Administering BMC Remedy Engine Overview How modify instructions work with incoming Figure 5-6 presents a sample scenario that demonstrates how to send modify instructions in an message. Figure 5-6: Using incoming to modify requests 1 AR System admin configured engine to allow modify entries. Key: 1234 Action: Modify Outgoing Field 1 Field 2 Field 3 Form Messenger engine parses modify instructions. 4 Incoming Mailbox account System AR Server Engine Mail Server 5 Underlying Database HD Incident 6.3 Engine Jklm Nop Qrst Abcd ef ghijkl mno Server ticket. modifies Key: Action: 1234 Request Modify ID: 55 Worklog: Service Patch 6 Joe to . User replies Key: 1234 Action: Modify Request ID: Francie Frontline sends with modify instructions. Sending a modify instruction to the engine 155

156 BMC Remedy Action Request System 7.0 Step 1 The AR System administrator at XYZ has enabled the BMC Remedy Engine to modify entries in the AR System server. He has associated the incoming and outgoing mailboxes. He has enabled the incoming mailbox to accept modify instructions. Finally, he has created and sent security keys to trusted users of the AR System, for example, the IT department. For more information, see Configuring the engine for modify actions on page 73. Note: The incoming and outgoing mailboxes in the engine can be one physical mailbox, performing both the incoming and outgoing functions. Step 2 Joe User has a serious problem with his PC. He needs an IT engineer to install the latest service patch and has submitted an entry on the HD Incident form (Request ID ). Francie Frontline, who has AR System Administrator privileges, is working on Joe s ticket. She needs Joe to verify his current PC configuration and modify his ticket with updated information. She sends an to Joe that includes the following mandatory parameters: Key Action: Modify Form name Server name Request ID Her to Joe must contain at least these items for modify instructions to work properly. She also includes names of fields that Joe can modify. After she sends her , a copy of the is stored in the Messages form and the is sent to Joe. Step 3 Joe User replies to the . He updates the worklog label/value pair in the , for example, Worklog! !: I m running Service Patch 6. Because he has used to submit and query AR System entries, he knows how to include additional fields to update information about the new department he was transferred to, for example,!department!: Product Marketing. 156 Chapter 5 Incoming

157 Administering BMC Remedy Engine Step 4 Step 5 The engine receives the reply from the mail server and verifies that Francie s original exists in the engine (in the AR System Messages form) and that the sender s address is contained in the recipient field of the original . It then parses the modify instruction in Joe s , and modifies the ticket in the HD Incident form. The engine returns the results to the sender, Joe User. If the had failed for some reason (for example, Joe modified the encryption value or he tried to use a different Request ID), the engine returns an error message that indicates faulty parameters or other problems. For more information, see the following detailed procedures. Sending modify instructions in plain text Executing a modify instruction is a two-step operation: Step 1 Step 2 The AR System administrator sends an outgoing message from the AR System Messages form to the user who wants to modify an entry. The message can be sent in plain text or HTML format. (To use HTML, see page 161.) The user replies to the message with new values of the entry the user wants to modify (see page 160). Sending modify instructions To send modify instructions to a user 1 Log in to BMC Remedy User as an AR System Administrator user. 2 Open the AR System Messages form in New mode, and enter the following information: a In the Mailbox Name field, select an outgoing mailbox. b In the To field, enter the name of the user you are sending the to. c In the Reply To field, enter the address of the incoming mailbox that has been configured to accept modify instructions. d Enter other information as needed, for example, an organization. Sending a modify instruction to the engine 157

158 BMC Remedy Action Request System Click the Plain Text Body tab to create an outgoing message (plain text) with the following information: AR System Server Name. AR System Login and Password to authenticate a user. Label Key to specify the security key the security key can be supplied by the Administrator in the outgoing message or provided by the user in the reply. The Action Label, which describes the type of action or instruction to be executed. In this example, the Action Label is set to Modify. Form or Schema name on which to execute the instruction. Request ID of the entry the user can modify. You can optionally provide field IDs or database names of fields that have values that can be modified. You must make sure the fields have permissions that allow users to make modifications. Following is the content of an outgoing message sent by the AR System administrator through the outgoing mailbox of the engine: Server: polycarp Login: Joe User Password: Key: Action: Modify Schema: HD Incident Request ID: ! !: This message allows Joe User to modify Request ID of the HD Incident form. The Problem Summary field has been specified in the outgoing message. Joe User can also modify additional fields in his reply by adding more field IDs. Figure 5-7 shows an outgoing message you might send to a user, in this case to Joe User. 158 Chapter 5 Incoming

159 Administering BMC Remedy Engine Figure 5-7: Sample outgoing message sent by administrator to user You can substitute field IDs for database names. For example, if the Problem Summary field is field ID 8, then you could replace the database name with its field identifier!8! and produce the same results:!8!: Optionally, you can enter comments before the field ID, for example: Enter problem summary!8!: Note: Since there are no content template labels, you can use a result template as its equivalent when performing a Modify action with incoming mail. When you send the , the engine appends an internal label called ##Modify##. The engine generates an encrypted value for this label using the Server Name, Schema Name, and Request ID (as shown in Figure 5-8). 4 Click Send to send the mail from the outgoing mailbox to the user. Sending a modify instruction to the engine 159

160 BMC Remedy Action Request System 7.0 Replying to containing modify instructions To reply to an containing modify instructions 1 Open your client. Joe User received an that looks like Figure 5-8. Figure 5-8: Modify instruction sent to user 2 Open a reply window for the that contains the modify instructions. Note: You must reply to the same mailbox as the one from which the was sent. 3 In the reply, modify parameters as needed. For example, you could assign values for!8!, the Problem Summary field. 160 Chapter 5 Incoming

161 Administering BMC Remedy Engine WARNING: The user who is replying cannot add additional submit, query or modify instructions to the . Do not change the Request ID, Schema name, or Server label/value pairs when replying to the administrator s . 4 Fill in any missing parameters as needed Login, Password (if there is a password), and Key. (For information about creating security keys, see Testing your mailbox configuration on page 65.) The following example shows the content of a sample reply from Joe User: Server: polycarp Login: Joe User Password: yadayada Key:1234 Action: Modify Schema: HD Incident Request ID: ! !: Bob Backline Comments!8!: Modified last name from Frank Frontline to Bob Backline ##Modify##:[$$ckI2UoIK4gNibZMvL7k7uI/eDhsoIU5JBTYvh5DMXaQnhPhicyCT/ g==$$] In this example, Joe User also modified the contents of the Short Description field (field ID 8). 5 Send the reply. When the incoming mailbox of the engine receives the reply from the user, it makes sure that the original sent by the administrator exists within the engine and that the sender s address is contained in the recipient field of the original outgoing . The engine then parses the . If you successfully modified the entry, the engine will return the results to the client. Otherwise, the engine returns an error message that indicates any missing parameters or other problems. Sending modify instructions in HTML In addition to the plain text format, you can also send modify messages from the AR System Messages form in HTML format. Using HTML form controls gives administrators greater control over the content that users can modify. By sending modify instructions in HTML, you are forcing users to respond to the modify instructions exclusively with the HTML controls you have defined. Sending a modify instruction to the engine 161

162 BMC Remedy Action Request System 7.0 To send modify instructions using HTML 1 Using the AR System Messages form, create an outgoing message in New mode. See Sending modify instructions in plain text on page 157 for sample contents of an outgoing message. 2 Click the HTML Body tab. 3 Enter contents like the following example: Server: polycarp<br> Login: Joe User<BR> Password <input type="password" name="password" size="15" maxlength="14"> <BR> Key:1234<BR> Action: Modify<BR> Form:HD Incident<BR> Request ID: 00005<BR> Assigned To <input type="text" name="!4!" size="20" value="assignee"> <BR> Short Description <input type="text" name="!8!" size="40" value="enter a short description"> <BR> Status <input type="radio" value="new" name="!7!"/> New <input type="radio" value="assigned" name="!7!" /> Assigned <input type="radio" value="wip" name="!7!"/> WIP <input type="radio" value="resolved" name="!7!"/> Resolved <input type="radio" value="closed" name="!7!"/> Closed <BR> This example of an HTML-formatted outgoing message allows Joe User to do the following task to entry 00005: Enter a password in an input type Password control field. When users enter their password, stars appear instead of the typed symbols or letters. Modify the contents of the Assigned To and Short Description fields. Modify the status in an input type Radio control field. Users can select only one radio button option. Unlike the plain text where users can modify additional fields in their reply by adding more field IDs, HTML is much more restrictive. The only fields that users can modify are the HTML controls you have defined in the outgoing message. As a result, using the HTML format can help prevent user errors. 162 Chapter 5 Incoming

163 Administering BMC Remedy Engine Another useful HTML format is including system information (for example, server name or form name) in hidden fields. The data is still within the message, but users do not see it. You make visible only those fields that users need to see, and disguise the rest as hidden fields. The following example is a Help Desk request message with Schema and Action as hidden fields with default values supplied: <h1>help Desk Request</h1><hr> <input type=hidden name="schema" value="help Desk"/> <input type=hidden name="action" value="submit"/> Name: <input type=text name="login"/><br/> Password: <input type=password name="password"/><br/> Problem Description: <input type=text name="short Description"/> Note: See any standard HTML reference book or reputable online source ( for how to define input type controls. 4 Send the outgoing . The user will receive an that looks like Figure 5-9. Figure 5-9: Modify instruction (HTML format) sent to user Sending a modify instruction to the engine 163

164 BMC Remedy Action Request System To execute the modification, reply to the received with the modified values for the HTML fields that you can see and have permission to change. Figure 5-10: Modify instruction (HTML format) sent to user Using the HTML controls you have defined, click in a field to modify its contents, for example, enter Assigning this ticket to Bob Backline in the Short Description field. Also observe that Joe s password is encrypted (Figure 5-10). With HTML, users can modify only the fields you provide. As a result, creating outgoing HTML requires some planning by administrators. For example, if Joe User could not enter his password, the engine would reject the modify action due to permission problems. is no different than any other AR System client. Like logging in to BMC Remedy User, he could not use to log in to the engine without entering a password. 164 Chapter 5 Incoming

165 Administering BMC Remedy Engine Additional restrictions Remember the following restrictions when using to modify entries: The engine does not support the Modify All operation. Only one entry can be modified with one modify instruction. However, you can include multiple modify instructions in one message if you include the full login information (server, login, and password) for each entry that you want to modify, as in the following example: Server: polycarp Login: Francie Frontline Password: Key:1234 Action: Modify Schema: HD Incident Request ID: ! !: Server: polycarp Login: Francie Frontline Password: Key:1234 Action: Modify Schema: HD Incident Request ID: ! !: You can combine the modify instruction with submit or query instructions in a single message, provided multiple instructions (modify with submit or query) have been sent from the administrator. Users cannot add new instructions when replying to the message containing modify instructions. Sending a modify instruction to the engine 165

166 BMC Remedy Action Request System 7.0 Overview Using workflow to modify requests Figure 5-11 presents a sample scenario that demonstrates how to use workflow to modify requests. Figure 5-11: Using workflow to modify requests AR System Server 4 AR System verifies security mechanisms and modifies the request. 1 AR configured System incoming admin mailbox modify actions. to accept Created security key. Engine Incoming Mailbox Outgoing Mailbox 2 AR System receives submit request. Filter workflow triggers Notify action. sent includes Modify template. Mail Server 3 User Reply receives includes . modify Login information: Security and key password Modify action keyword 166 Chapter 5 Incoming

167 Administering BMC Remedy Engine Step 1 The AR System administrator at XYZ has enabled the BMC Remedy Engine to modify entries in the AR System server. He has associated the incoming and outgoing mailboxes, enabled the incoming mailbox to accept modify instructions, and created and sent security keys to trusted users of the AR System. For more information, see Configuring the engine for modify actions on page 73. Note: The incoming and outgoing mailboxes in the engine can be one physical mailbox, performing both the incoming and outgoing functions. Step 2 Step 3 The AR System receives a submit request. A filter uses to send a notification that a request has been received. This was formatted using a modify template. The user receives the message in her client and then replies to it. She modifies the request by entering the following information: Login and password Security key Modifications to values of fields She presses the Send button to reply back to the AR System server. Step 4 The AR System server verifies the security key, the user s address, and the Request ID. These security mechanisms make sure that only the entry sent for modification is being modified and that it is being modified by the user who the original was sent to. Creating workflow to modify requests The following example walks you through the procedure for creating workflow to modify requests. The example is simple but complete, and you can easily add more functionality. For example, you could create a Run If qualification in your filter to search for records marked Urgent and that are assigned to your Managers group. In this example, make sure that the Demo user is still active and has an address that works with the engine. Make sure your incoming and outgoing mailboxes work correctly. Finally, set the polling intervals on your incoming and outgoing mailboxes to one minute so that you can quickly verify your results. Overview Using workflow to modify requests 167

168 BMC Remedy Action Request System 7.0 Creating a security key Use the following values to create an AR System Security record. You must provide a security key for every user who sends modify instructions to the engine, in this example, Demo. To create a security key 1 In BMC Remedy User, open the AR System Security form in New mode. 2 Set the Status field to Enabled. 3 In the Key field, define your security key, for example, patience. 4 Enter Demo as the User Name. 5 Set the Force For Mailbox field to No. 6 Set the Force From Addresses to No. 7 Set the Expires field to No. 8 Leave the rest of the fields blank and save the record. Creating a sample form for your modify example You are creating a sample form used exclusively for the purposes of this exercise. Later you will create and modify a record in this form to verify the workflow process. To create a sample form 1 Create a new form and name it appropriately, for example, Modify Workflow. 2 Do not add any new fields. 3 Save the form. Creating filter workflow that triggers a Notify action Use the following information to create a filter that executes on the Submit condition of the Modify Workflow form and triggers a Notify action. 168 Chapter 5 Incoming

169 To create filter workflow 1 Create a filter. 2 Enter a filter name, for example, Modify Filter. 3 Select Modify Workflow as the Form Name. 4 Select Submit as the Execute On condition. Administering BMC Remedy Engine 5 Leave the Run If condition blank. After you verify that you can use your filter workflow to modify requests, you can add a Run If qualification later. 6 Click the If Action tab. 7 From the New Action list, select Notify. 8 In the User Name field, enter Demo. 9 From the Mechanism list, select In the Subject field, enter Modify Workflow. 11 In the Text field, enter the following information as the text of the message: Login: Password: Key: Action: Modify Form: Modify 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 engine to modify an entry on the AR System server. The Modify action is valid only in Reply with Result s. For more information, see Modify action on page Save your filter. Exporting an template Export an template from the Modify Workflow form. For more information, see Exporting mail templates on page 188. Overview Using workflow to modify requests 169

170 BMC Remedy Action Request System 7.0 To export templates 1 In BMC Remedy Administrator, choose Tools > Export Mail Templates. 2 From the Forms to Export list, select the Modify Workflow form. 3 Click Export. 4 Save the template in.arm format to your desktop. 5 Open the template in a text editor. Creating a submit Here you open a new message and paste the contents of the exported mail template into the new . You use this to submit a record to the Modify Workflow form. To create a test 1 Create a new in your client. 2 Address the to the BMC Remedy inbox account. 3 Create a subject line, for example, Modify Workflow. 4 Copy and paste the contents of the exported template into the new , and then fill out the required information for the template, for example: # # File exported Tue Sep 21 15:34: # Schema: Modify Workflow Server: POLYCARP.eng.remedy.com Login: Demo Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full Submitter!2!: Demo Short Description!8!: Test 5 Send the to the incoming mailbox. 170 Chapter 5 Incoming

171 Replying to notifications Administering BMC Remedy Engine The client sends your submit to the incoming mailbox on the mail server. The engine, after receiving the from the mail server, parses the instructions in your , and makes the submit API calls to the AR System server. The server then creates a record in the Modify Workflow form. The incoming mailbox is configured to reply with results and generates an response. In addition, when a record is submitted, filter workflow triggers a Notify action that includes instructions for modifying the record. The following procedure describes how you reply to notifications generated by workflow. To reply to notifications 1 Open the AR System Messages form in Search mode. 2 Confirm that the incoming mailbox has received your message, and then sent the Reply with Result (as shown in Figure 5-12). Figure 5-12: Incoming and outgoing messages in Messages form Overview Using workflow to modify requests 171

172 BMC Remedy Action Request System In BMC Remedy User, open the Modify Workflow form in Search mode. 4 Make sure a new record was created in the Modify Workflow form. 5 Check for new mail in your mail client. If you properly configured the engine and all your permissions are working correctly, you should receive an notification (as shown in Figure 5-13) from the filter that you created previously. Figure 5-13: Notification (sent from filter) with modify key Figure 5-13 shows the modify key added to the notification: ##Modify##:[$$ckI2UoIK4gNQ0qROehOucPFOokiXb/DfA07EiNObusaHtOquCV/ FSA==$$] Important: You cannot modify a record through without this ##Modify## key. Do not edit this key in any way! 6 Reply to the returned Chapter 5 Incoming

173 Administering BMC Remedy Engine 7 Enter the following information into the body of the Login: Demo Password: Key: patience Action: Modify Form: Modify Workflow Request ID: Submitter!2!: Demo Short Description:!8!: Modifying requests with workflow is great! ##Modify##:[$$ckI2UoIK4gOt6aqHF2QE9x5d1nqwf6FJLifugKurp68lQH9XRehnEw= =$$] Make sure you add the Login and security key. Update the Short Description so that you can verify that modifications work on records in the Modify Workflow form. 8 Send the reply . 9 In the AR System Messages form, confirm that the incoming mailbox has received the with the modify instruction (as shown in Figure 5-14). Figure 5-14: Modify message returned to incoming mailbox Overview Using workflow to modify requests 173

174 BMC Remedy Action Request System In BMC Remedy User, refresh the query results of the Modify Workflow form. The modify action should have modified the Short Description in the record. Searching for an entry to modify Advanced solution This advanced solution builds on all the information you have learned up to now, for example, sending query and modify instructions to the engine, the use of templates, and so on. The procedure assumes you have created a form named TestSecurityForm containing at least the core fields. To search for an entry to modify 1 Make sure you have an incoming mailbox and an outgoing mailbox configured and associated with one another. 2 Set Enable Modify Actions to Yes in the AR System Mailbox Configuration form for the incoming mailbox. 3 Make sure you have a valid security key. 4 Create a template (TestModify) that includes a modify action. You will use this template for the reply ; see the Result Template label in step 6. Server: polycarp Login: Password: Key: Action: Modify Form: TestSecurityForm Request ID: [$$#$$Request ID$$#$$]!2!:!8!: Because this template replaces the hard-coded label/value pair (Request ID: ) with a variable value (Request ID:[$$#$$Request ID$$#$$]), you can construct an that gives you the flexibility to search for a specific parameter. 5 Add the TestModify template to the AR System Templates form. 174 Chapter 5 Incoming

175 Administering BMC Remedy Engine 6 Use your mail client to create an incoming mail. Include a Query action in the body of your . For example: Server: polycarp Login: Demo Password: Action: Query Form: TestSecurityForm Qualification: 'Request ID' = " " Result Template: TestModify This provides all the information required for the engine to perform the query action, and then to perform the modify action in the TestModify template. Tip: If the Qualification was part of the TestModify template, you could have omitted the Qualification line from the . 7 Send your to the incoming mailbox. The engine generates a reply (Figure 5-15) to the Query action, using the template you created in step 4 and specified as the Result Template. You can see that the Request ID value found from the query was substituted in the reply, using the variable in the template. Searching for an entry to modify Advanced solution 175

176 BMC Remedy Action Request System 7.0 Figure 5-15: Reply generated from engine Request ID variable substituted in reply, based on template Key included in reply generated by engine The engine also creates a Modify Key based on the information in the Action, Form, and Request ID and adds it to the . 8 Open the reply and modify the parameters as required. For example, add values in!2! (a different name) and!8! (modifying the short description). Do not change the Action, Form, and Request ID label/value pairs. 9 Fill in any essential missing parameters Login, Password (if there is a password), and Key. 10 Send the reply with the modifications included. Note: You must reply to the same mailbox as the one from which the was sent. The engine parses the and the server modifies the entry. The engine then sends you a confirmation message, as shown in Figure Chapter 5 Incoming

177 Administering BMC Remedy Engine Figure 5-16: Confirmation that modify action was successful You can perform a search on the form to verify the result. Using variables with templates With incoming , you can also use variables in templates. Variables are useful when you need to be able to send different values for the fields to submit an entry. Variables allow you to substitute different values for appropriate fields. Use the following syntax for variables: #$$Variable Name$$# If you expect the value of a variable to span multiple lines, then enclose the variable with brackets: [$$ $$] Using variables with templates 177

178 BMC Remedy Action Request System 7.0 The following example of a template file (.arm file) submits a new employee name into the Employee Information form: Schema: Employee Information Server: server1 Action: Submit Short Description!8!: $DATABASE$ Submitter!2!:$USER$ Employee Name!VEmployee Name!: [$$#$$VEmployee_Name$$#$$] The characters between exclamation marks exactly match the field ID or database name of the field on the form. The variable is called VEmployee_Name. Since the variable might span multiple lines, it is enclosed between brackets [$$ $$]. When you send a submit instruction, you also can provide a value for variable $$VEmployee_Name$$, as shown in the following example: Schema: Employee Information Server: server1 Action: Submit Short Description!8!: $DATABASE$ Submitter!2!:$USER$!VEmployee_Name!: [$$Joe Smith$$] Displaying advanced options for incoming For incoming , the most important use of the Advanced Options tab is to view message information and errors of incoming . This information is used mostly for troubleshooting. The Attachment Alternatives tab (Figure 5-17) displays any attachments in the incoming . It displays the links to the message as it is rendered by the engine in plain text, HTML, and client formats. 178 Chapter 5 Incoming

179 Administering BMC Remedy Engine Figure 5-17: Attachment alternatives information for incoming Formats of incoming message displayed For more information, see Chapter 7, Troubleshooting. To display advanced options 1 Open the AR System Messages form in Search mode. 2 Select an incoming message. 3 Select Yes in the Display Advanced Options field of the AR System Message form. 4 Select one of the advanced option tabs: Advanced Options, Message Information, or Errors. Note: For incoming , you typically will not see information under the Templates and Variable Replacement tabs. Displaying advanced options for incoming 179

180 BMC Remedy Action Request System 7.0 Message Information tab The Message Information tab records status information about incoming , such as its Message ID, the date the was received, and how the message was parsed, as shown in Figure Figure 5-18: Message information for incoming 180 Chapter 5 Incoming

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

182 BMC Remedy Action Request System Chapter 5 Incoming

183 Chapter 6 Using templates This chapter provides information and instructions for creating and using templates for outgoing and incoming . The following topics are provided: Overview templates (page 184) Creating templates (page 188) Using label/value pairs in templates (page 191) Storing templates in the AR System Templates form (page 209) Adding attachments to HTML templates (page 211) Preparing templates after an upgrade (page 215) Overview Sending incoming with user instructions (page 216) Using templates 183

184 BMC Remedy Action Request System 7.0 Overview templates This chapter describes the various types of templates, their use in incoming and outgoing mailboxes, as well as label/value pairs. Labels are keywords unique in the engine and values are their data. Label/value pairs can be included in templates and used to instruct the engine to interact with your AR System server. Tip: The term template can be slightly misleading, because templates are more than simply the pattern of label/value pairs you export using BMC Remedy Administrator. In addition to exported label/value pairs, a variety of templates function as the actual headers, footers, and content of your messages. templates serve two main functions for incoming and outgoing messages: For incoming messages ( that users send to an incoming mailbox), users can include templates in their s that contain specially formatted instructions. These instructions use combinations of field labels and their values, usually referred to as label/value pairs. The engine parses (that is, translates) these instructions into commands to the AR System server to perform a query, submit or modify an entry, or complete any other such action. For outgoing messages (sent by the engine using an outgoing mailbox), templates can provide formatting of content in messages that include the results of queries or various other requests. Templates used for incoming and outgoing messages can be formatted using plain text, HTML, or XML. Templates are defined and stored in forms on the AR System server and can be retrieved for use by the engine when called upon by incoming or outgoing mail. 184 Chapter 6 Using templates

185 Administering BMC Remedy Engine Types of templates You can create specific templates for various functions. This section presents an overview of the different types of templates, which are all described in more detail later in this chapter. Incoming and outgoing mail templates You can create separate templates to specify different formats for incoming and outgoing mail. Content templates. Used for outgoing messages. These templates can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. They can also contain plain text or reserved variables. You can create these templates in a text editor (shown in the following figure), or export them using BMC Remedy Administrator, selecting the form and fields that are to be contained in the template. The content template can also contain formatting instructions and label/ value pairs to specify a header, footer, result, or status template. A content template is attached using the AR System Messages form or using workflow with filters and escalations. Figure 6-1: Content template plain text When using a content template with workflow, make sure that you include the fields specified in the content template in the Fields tab of the Notify action. Content templates can also be formatted in HTML, similar to the result template shown in Figure 6-3 on page 186. Overview templates 185

186 BMC Remedy Action Request System 7.0 Header and footer templates. Used to place lines of text or a graphic at the beginning or end of a message. (A header template is shown in Figure 6-2.) They can be specified in the outgoing using the AR System Messages form. If they are specified in content templates or an body as label/value pairs, they will be applied to the reply. Figure 6-2: Header and footer template HTML Result templates. Defines the format to use when replying to an incoming instruction with the results of an action. A label/value pair must be specified in the containing the action. Result templates can be either HTML or plain text. Figure 6-3 shows an example of an HTML-formatted version of a result template. Figure 6-3: Result template HTML Status templates. Used when the execution of an incoming instruction results in an error (as shown in Figure 6-4). A label/value pair must be specified to include specific status information in the or content template. Status templates can be either HTML or plain text. (For more information, see Reserved variables on page 207.) 186 Chapter 6 Using templates

187 Administering BMC Remedy Engine Figure 6-4: Status template HTML User-defined instruction templates A special use of templates are user-defined instruction templates that enable administrators to associate a template with an incoming by way of an entry in the AR System User Instruction Templates form. When the user sends an with the appropriate entries, the BMC Remedy Engine executes the relevant template. Using this feature, the administrator can set up variable substitutions to be used in an with minimal input from the user. The associated template supplies the rest of the information. For example, the template shown in Figure 6-5 logs the user Demo in to the server reepicheep, queries the HD Incident form for all tickets with an urgent status, and returns the full information about all fields that this user has access to. But all that the user needs to do is send an incoming with the Action label/value pair that identifies the user instruction, for example, Action: Urgent. Overview templates 187

188 BMC Remedy Action Request System 7.0 Figure 6-5: User-Defined instruction template Creating templates Exporting mail templates User-defined templates look the same as other templates and are stored in the AR System Templates form. For more information, see Action label on page 194 and Overview Sending incoming with user instructions on page 216. In BMC Remedy Administrator, you can generate the templates associated with a particular form by choosing Tools > Export Mail Templates. The templates are generated as text files. You can modify the templates in a text editor so that they are in a different format and include all necessary specifications. You can also create your own custom template using any text editor. These templates must adhere to the rules outlined in this guide if they are to include fields, variables, and label/value pairs. The mail template displays all of the fields that are visible in the selected view and that all users have permission to update. Therefore, make sure that all fields that require a value are visible in the selected view and that the Allow Any User To Submit check box is selected before performing the following procedure. The Export operation generates fields in the same order as in the default administrator view of the form. 188 Chapter 6 Using templates

189 Administering BMC Remedy Engine Hidden fields are omitted from templates even though they might have public permissions and are set to enable any user to submit. You can add any of the fields that are not exported to the template. The user can gain access to these fields if their security key, supplied user information, or their address connects to the correct user name and depending on how the mailbox was configured. If the user name used by the BMC Remedy Engine has access to this field, then the field is accessible. To export mail templates 1 In BMC Remedy Administrator, select a server to administer. 2 Choose Tools > Export Mail Templates. The Export Mail Templates dialog box appears. Figure 6-6: Export Mail Templates dialog box 3 From the Forms to Export list, select the form for which you want to generate mail templates. If you want to export more than one form, create a separate template for each form; that is, perform this procedure for each form. 4 Click Export to open the Export File dialog box. Creating templates 189

190 BMC Remedy Action Request System If you are creating a new file, specify where you want the templates stored, and then enter a file name. Otherwise, if you specify an existing folder and file name, you have two choices: Overwrite Overwrites the mail template of an existing file. This option is useful when you are re-exporting a template that has changed. Append Appends the contents to an existing file. If several templates are in a single file, the mail processor will not be able to process the request. 6 Save your changes. The template is saved as a single text file with an *.arm extension. Using the AR System Templates form, users can associate these files with their mail messages. The following example shows an template exported using BMC Remedy Administrator. # # File exported Fri Apr 30 09:54: # Schema: HD Server: POLYCARP.eng.remedy.com Login: Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full In general, lines beginning with a pound sign (#) are treated as comments, and can occur anywhere in the message. Comments are optional and can be retained or deleted. 190 Chapter 6 Using templates

191 Using label/value pairs in templates Administering BMC Remedy Engine For the most part, 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 engine is not case sensitive when parsing the labels. The following table lists valid labels; each label is discussed in more detail following the table. Label Description Incoming Outgoing Aliases Page Form Name of an AR System form. Yes No Schema page 192 Server Login Password TCP Port RPC Number Authentication Language Action Format Qualification Server that will be affected by the instruction. User name used when executing the instruction. Password used when executing the instruction. TCP port used when logging in to the AR System server. RPC number used when logging in to the AR System server. Authentication string used when logging in to the AR System server. Language used when logging in to the AR System server. Denotes the instruction to be executed. Specifies the format of the information. Qualification for a query-based instruction. Yes No page 192 Yes No User page 193 User Name Name Login Yes No page 193 Yes No TCP page 193 Yes No RPC page 193 Yes No page 193 Yes No page 194 Yes No Instruction page 194 Yes Yes page 196 Yes No Query page 197 Search Using label/value pairs in templates 191

192 BMC Remedy Action Request System 7.0 Label Description Incoming Outgoing Aliases Page Result Template Status Template Header Template Footer Template!Name/ID! Key Request ID The name of the template to use in the reply. The name of the template to use when Status Information is returned. The template to be used as the header in the reply . The template to be used as the footer in the reply . The database name or ID of an AR System Form Field. The key associated with a given sender or user. The Request ID of the entry on which the possible action must be executed. Yes No Result ResultTemplate page 197 Yes No Status page 198 StatusTemplate No Yes Header page 198 HeaderTemplate No Yes Footer FooterTemplate page 198 Yes Yes page 199 Yes No Encryption Key page 199 Encryption Yes No Entry ID page 200 EntryID RequestID Form label The Form label identifies the form that the instruction will use. If no AR System form is specified or the specified form does not exist, the mail process verifies whether a default Workflow form was defined in the AR System Mailbox Configuration form. If not, the item is rejected because a form must be specified. The alias for this label is Schema. An example of a Form label/value pair is Form:<form_name>. Server label The Server label identifies the server that will be affected by the instruction. If no server is specified or the specified server does not exist, the mail process defaults to the server information specified in the Daemon.properties file. An example of a Server label/value pair is Server:<server_name>. (For more information, see Using the Daemon.properties file on page 233.) 192 Chapter 6 Using templates

193 Administering BMC Remedy Engine Login, Password, and TCP Port labels The Login and Password labels identify the user name and password used when executing the instruction. You can configure exactly how the user name is to be determined for an incoming Set a security key in the AR System Security form. You must add Key:<security_key> to the . If Key:<security_key> matches an entry in the AR System Security form, then the corresponding user name is used. Use the supplied user information: user login name, password, possible authentication, possible language, possible RPC, and possible TCP inside the using the appropriate labels and values. Use the sender s address: The BMC Remedy Engine will search through the User form for the appropriate user name by searching for the address. It will use the first user it finds whose address corresponds. The passwords and security keys will be encrypted in the AR System Messages form. The aliases for Login are User, User Name, Name, and Login Name. Note: If you try to send an in an HTML template, do not use a colon in the Login, Name, or Password labels, for example: Login: <input type="text" name="! " size=50/>. Use instead the format: Login <input type="text" name="! " size=50/> With this format, the engine can parse correctly that Login is a label for a field on the form and not an instruction. The TCP Port label identifies the TCP/IP port of the AR System server, if your AR System server is not using Portmapper. The alias for TCP Port is TCP. RPC Number and Authentication labels These labels define the RPC number for the destination server (usually involved when the user is connecting to private servers) and the name of the external authentication service that is used to authenticate the user. These values are the same as those used when logging in to the AR System server. The alias for RPC Number is RPC. Using label/value pairs in templates 193

194 BMC Remedy Action Request System 7.0 Language label Action label The Language label defines the locale used when logging in to the AR System server. If no language is specified, the default values are used. The values are the same as they are in the BMC Remedy Administrator and AR System clients. The format of the Language label/value pair is Language:<language>, for example, Language:en_US. The Action label defines the operation to perform on a specific AR System form. The Action label/value pair are required in the incoming so that the parser can generate valid instructions. Valid actions are Submit, Query, Modify, and a user-defined value. If no value is given for the label, the will only be logged and no actual execution will take place. An alias for Action is Instruction. Valid values for this label are in Table 6-1, and explained in more detail after the table. Table 6-1: Values applied to AR System action labels Value Submit Query Modify User-Defined Description Submits a new entry on a specific AR System form. This is valid within any incoming . The syntax is Action:Submit. Searches for entries on a specific AR System form. The syntax is Action:Query. Modifies a specific entry contained within a specific AR System form. This is only valid in reply s (that is, s that have been sent to the user from an AR System server). The syntax is Action:Modify. An instruction defined by the administrator. The syntax is Action:<admin_defined text>. Submit action By using the Submit action in an , users can enter values for field labels, and submit a new record. You can see an example of a template with a Submit action in Sending a submit instruction to the engine on page Chapter 6 Using templates

195 Query action Administering BMC Remedy Engine The Query action lets you search for existing entries. To increase server performance, you can configure a limit to how many matches are returned; the maximum number of matches allowed is returned in the message. If a request exceeds the configured search match limit, an additional message is provided that indicates what the limit is. See the Configuring guide for information about configuring limits. For sample templates with Search (Query) actions, see Sending a query instruction to the engine on page 144. Modify action The Modify action enables you to modify existing entries, but due to the nature of this command and the security implications, the command can be executed only under the following conditions: The message containing the modify action must be sent from an AR System administrator to the user. The user can only change field values and cannot add new actions, or modify existing actions when replying to the that contains the modify action. The user must not modify the modify key included in the . The sender or the user of the must supply a valid Security Key. Note: Do not modify the Password field (field ID 102). The incoming mailbox must be configured to allow modifications. For more information, see Configuring the engine for modify actions on page 73. In the outgoing mailbox, make sure the Delete Outgoing Notification Messages field is set to No. You cannot modify a record by if you delete outgoing messages. The BMC Remedy Engine will insert a special label and value into the if the contains a Modify action. This special label/value pair is defined as follows: ##Modify##:[$$the encrypted information$$] Using label/value pairs in templates 195

196 BMC Remedy Action Request System 7.0 Format label The encrypted value contains information, which the BMC Remedy Engine uses to determine the following items: The Request ID of the being sent. The AR System server to which the was submitted. Form name. For more information, see Overview Using workflow to modify requests on page 166 and Sending a modify instruction to the engine on page 154. User-defined instruction This action is a text string that has been determined by the AR System administrator and is used as a value for an Action label. A user-defined value can consist of any text, as long as it is defined in the AR System User Instruction Templates form for user-defined instructions. For more information, see Overview Sending incoming with user instructions on page 216. For Query, Submit, and Modify actions, you can specify that requested information be formatted in full or short form by entering Full or Short after this keyword. An example of a Format label/value pair is Format:Full. The Full format lists the information for all accessible fields, with each entry separated by a line of hyphens. The Short format returns only the fields defined in the results list. If no fields are defined for the results list, it returns the Short Description field. In Submit and Modify actions, only use the Format label if the advanced configuration setting Reply with Entry is set to Yes for the incoming mailbox. For Query, the default format is Full. All matching requests are listed in the body of the response, one after another. 196 Chapter 6 Using templates

197 Administering BMC Remedy Engine Qualification label Result Template label The Qualification label and its value are required only for a query-based instruction. The value can be any properly formatted search. All of the restrictions that apply to the Advanced Search bar in BMC Remedy User apply when performed through . The following is a sample qualification string: Qualification: 'Source' = "Phone" OR 'Source' = " " A null value will be treated as if it is a return all records query, such as 1 = 1. Aliases for this label are Query and Search. If the engine is configured to send an reply, you can specify a result template that formats the reply for you. You include the Result Template label, and specify the template name as the value. The Result Template label defines the template to use when replying to an incoming containing query instructions. The Result template is usually associated with a particular form. This template consists of label/value pairs and variables (see page 203 for more information) that correspond to fields on the AR System form being queried. These variables are replaced by the data found on the form based on the instruction being executed. For example, you can include variables in your template that let users click a direct access URL to open a specific Request ID: <TD width="17%"><a href=" ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request ID$$#">#$$Request ID$$#</a> </TD> Figure A-3 on page 271 illustrates how this variables is used in a result template. The value given for this Result Template label is the name or Request ID of the template contained in the AR System Template form. When the BMC Remedy Engine receives this label and value, it will retrieve the template file and use it as required. Aliases for this label are Result and ResultTemplate. An example of a result template label/value pair is Result:<result_template_name>. For more instructions, see Using HTML result templates with outgoing on page 131 and Creating an reply using result templates in HTML format on page 270. Using label/value pairs in templates 197

198 BMC Remedy Action Request System 7.0 Status Template label The Status Template label is the name of the template to use when status information is returned. The template consists of label/value pairs and variables that are replaced with relevant data. These variables correspond to the status information returned if any errors occurred while executing one of the instructions; they make use of reserved words. (For more information, see Reserved variables on page 207.) This template does not have to be related to a particular form; the variables are specific to status information and therefore can be used for any instruction on any form. The value given for the Status Template label is the name or Request ID of the status template contained on the AR System Template form. When the BMC Remedy Engine receives this label/ value pair, it will retrieve the template and use it as required. Aliases for this label are Status and StatusTemplate. An example of a status template label/ value pair is StatusTemplate:<status_template_name>. Header Template and Footer Template labels These labels define the templates used in the creation of outgoing where the header is inserted at the beginning of the and the footer is inserted at the end of the . If the templates are used, however, within a Query action block that is, after an Action: Query label/value pair then the header or footer or both are inserted before or after (or both before and after) each entry that is retrieved when the action is executed. In this way, entries are clearly separated from each other. The Header and Footer templates typically contain basic text, or they could be HTML documents with logos, graphics, and decorative typefaces. The value given for this label is the name or Request ID of a template contained on the AR System Template form. When the BMC Remedy Engine receives this label/value pair, it will retrieve the template and use it as required. The label/value pair method is used when requesting results from a server by way of . Aliases for the Header Template are Header and HeaderTemplate; aliases for the Footer Template are Footer and FooterTemplate. An example of a header template label/value pair is HeaderTemplate:<header_template_name>. 198 Chapter 6 Using templates

199 Administering BMC Remedy Engine!Name! or!id! labels Key label These labels indicate an AR System field or the value of a specific variable. The exclamation marks are required to surround the field name or the ID number. For example, field ID 8 is!8!. A colon (:) is placed after the second exclamation point as a delimiter, for example:!8! : Short description information Blanks are acceptable. If any characters other than digits and spaces are between the exclamation points, the reference is not recognized as a field ID. The argument to the ID/name label should be of the same datatype as that of the field (datatype information need not be included explicitly as the parser will determine the appropriate datatype of the field by default). If this is a query action, and the argument is of a different datatype than defined for this field, an error will be generated. Labels for fields need not be present in any specific order within an message. You can precede the field name/id label with any text that you want to include. This text will not be parsed by the engine. It is common practice to include the actual field name in this way: Submitter!2!: $USER$ In the previous example, the text Submitter will be treated as regular text by the engine. The field ID!2! will be parsed and the variable $USER$ will be the value used for any submit or query action that might have been specified. Only fields that have values are used in the request. Fields that do not have values are ignored. If you want to specify the Request ID for join forms, use the Request IDs of the forms referenced by the join form separated by a vertical bar. For example, a join form Request ID might appear as TT TT If your incoming mailbox is configured to require a security key, then the Key label/value pair must be present in the incoming message. A key is required to use the Modify action. The passwords and security keys will be encrypted in the AR System Messages form. Aliases for the Key label are Encryption Key and Encryption. An example of a Key label/value pair is Key:<test_key>. Using label/value pairs in templates 199

200 BMC Remedy Action Request System 7.0 Request ID label Label/value pair formats For more information, see Configuring incoming mailbox security on page 69. This label is only valid for the Modify action and defines the Request ID or Entry ID of an entry on the corresponding form against which the Modify action is to be executed. The Request ID is required for a Modify action as it serves to identify the specific form entry you want to modify. Aliases for the Request ID are Entry ID, EntryID, and RequestID. An example of a request ID label/value pair is RequestID: Your must use specific syntax for label/value pairs so that the parser can extract the required information. Each of the following formats can be used in plain text, HTML, or XML documents. Basic format The basic format is the simplest. You can associate a label with a constant value or a variable value. The labels and associated constant values are written as follows: Label:[$$Value$$] The opening and closing $$ enable the parser to extract the value from the , including situations where the value incorporates multiple lines. If the value does not incorporate multiple lines, the label/value pair can be written as follows: Label:Value Tip: You should use the [$$... $$] variable syntax when the BMC Remedy Engine needs to parse multi-line values. Strictly speaking, you do not need to use this multi-line syntax for all label/value pairs, but it is a good practice to adopt if you think the values in a variable might exceed a single line. The label and value do not have to be left justified, and can be prefaced by text on the same line. You do not have to surround the label with any special characters. 200 Chapter 6 Using templates

201 Administering BMC Remedy Engine You can associate a label with a variable also. A variable is written as follows: #$$variable_name$$# When used in a label/value format: Label:[$$#$$variable_name_Value$$#$$] XML format The XML format is as follows: <Label>Value</Label> AR System fields are treated differently. The format is as follows: <Field ID="!Field_ID!">Field Value</Field> or: <Field Name="!Field_Name!">Field Value</Field> Variables are referenced as #$$variable_name$$# as in the Basic format. To view a template using XML, see Using XML result templates with outgoing on page 135. HTML format The four major HTML field types are: Text fields Radio buttons Checkbox buttons Menu field These types have a fixed format in HTML. In HTML, however, an editor will automatically generate the correct format when filling in any missing field values. You can still use the Basic format within the HTML document. The corresponding fields can be used in situations where input is required from the user. The client must allow or support the ability to edit HTML fields directly; such an example would be Microsoft Outlook when it is configured to edit s with Microsoft Word. To create a template using HTML field types, see Sending outgoing in HTML on page 111. The name tag represents the label, and the value tag represents the value. Using label/value pairs in templates 201

202 BMC Remedy Action Request System 7.0 Text field In HTML, a text field will typically look as follows: <input type="text" name="label" size="20" value ="Value"> This represents a text field into which data can be typed so it easily represents a label/value pair. The name tag contains a label, such as Action, and the value tag will contain a corresponding value, such as Query. Radio buttons These allow you to design a document where the user can select from a given range of possibilities. Unlike a text field where only one set of tags between the <> markers represent a label/value pair, radio buttons can contain several sets of tags that comprise one instruction label and several values. An example follows: <input type="radio" value ="Submit" checked name="action" > <input type="radio" value ="Query" name="action"> This represents two radio buttons grouped together under the name Action. The values for the radio buttons would be Submit and Query. The selected value would be determined by the word checked. The resulting label/value pair would be Action:Submit. Checkbox buttons Checkbox buttons allow you to design a document where there are several possibilities, but those possibilities are not grouped together. An example follows: <input type="checkbox" name="label" value ="Value"> or <input type="checkbox" name="label" value ="Value" checked> In the first example, the label and value will not be used because the word checked is not included in the definition. But in the second example, the label and value will be used because the box has been checked. This field can give the user the ability to select the parameters that are valid and those that are not. Menu field The menu field acts as a selection box where you will be able to create a label from which any specific value can be selected from a range. In the following example, the Action label has possible values of Modify, Submit, and Query. 202 Chapter 6 Using templates

203 Administering BMC Remedy Engine <select size="1" name="action"> <option value="modify">modify the entry</option> <option selected value="submit">submit the entry</option> <option value="query">query the entry</option> </select> The type is a select HTML field, the label is Action and the values are Modify, Submit, and Query. The label/value pair to be used is determined by the tag containing the word selected. The menu field also allows the user to specify different visible text in the field with the correct field values defined underneath. Global and local parameter declarations Variables Any parameter defined in the before an Action label is regarded as global and applies to all the actions within the . As a result, you do not have to repeat parameters, such as login information or form names, for each and every instruction. If the parameter is defined again after an action statement, then that parameter takes precedence over the global parameter for that action only. For more information, see Creating an content template with Submit and Query actions on page 268. The use of variables allows the administrator to create generic templates. Variables are used only with templates that are to be used as user-defined instruction templates for incoming , result templates for incoming , or as content templates for new outgoing . They are placeholders that are replaced by specific values defined when: The user instruction is executed and where the values are defined by a user sending the executing this user instruction. The template for new outgoing s is used as a content template. The variables are defined by values of the fields in the entry that triggers the notification. Variables can be used in place of values in the label/value pairs in templates. The variable is replaced by a value at execution time. The variable is defined as follows: #$$variable_name$$# Using label/value pairs in templates 203

204 BMC Remedy Action Request System 7.0 When used in a label/value format, use the following syntax: Label:[$$#$$Value$$#$$] For more information about label/value formats, see page 200. The name of the variable can be the same as an AR System field, so there are no restrictions if used in the context of an AR System form. This allows you to use existing AR System field values to define the value of a variable. The variable value is retrieved from the same!field ID! label as that of AR System fields so the variable name might also be the name or ID of an existing AR System field. However, in content templates used for outgoing s, variables for field values must use the field database name, not the field ID. See Using variables with notifications on page 205 for specific examples. For outgoing s, the variable value is determined in the following order: Step 1 Step 2 Step 3 If you supply an attachment in the Values attachment field of the Attachment Alternatives tab of the AR System Messages form, the attachment will be used to determine the values for variables contained in the template. See Using the Attachment Alternatives tab on page 124 for more information about how to do this. If you did not supply an attachment in the Values attachment field, but supplied information in Field Values, or obtained a value using a qualification in the Qualification field of the Variable Replacement tab of the AR System Messages form, the information will be used to determine values for variables contained in the template. For more information, see Using the Variable Replacement tab on page 119. If you did not supply field values, but your content template contained a query to obtain information to substitute in the , the query information will be used to generate the message. For query information to be used, a form, server, and qualification must be supplied. If any one of these items is missing, the message creation will fail. 204 Chapter 6 Using templates

205 Variable examples Administering BMC Remedy Engine The following is an example of a field value used as a variable in a Query or Qualification: Query:[$$ Last Modified By = User AND Modified Date > #$$modified_date$$# $$] Inside the same template or defined in the user-defined instruction template received by way of the , this variable could be associated with a value as follows:!modified_date!:[$$21/01/2004$$] After the parser has extracted all the required information, the variable is replaced with the appropriate value, resulting in a query as follows: Query:[$$ Last Modified By = User AND Modified Date > 21/01/ 2004 $$] Note: Variables can only be used for form field values and qualifications. In addition, they do not work for Login or Server labels. For example, the variable Login: #$$Joe User$$# would not be correctly parsed by the engine and would return an unknown user error. Also, only local fields (fields after the Action label) can be substituted. Global fields (fields before the Action label) cannot be substituted. Finally, labels like Server, Schema, Login, Password, or Key are considered to be global and cannot be substituted. Using variables with notifications When creating templates to be filled in using notifications, the template variables for field values must use the field database name as the variable name, not the field ID. This is because the server uses the field name (database name) to assign the values in the AR System Messages form. For example, if the user has a template to mail out the user information through a notification that looks like the following, it will not work for notifications: Login Name : #$$101$$# Password : #$$102$$# Group List : #$$104$$# Full Name : #$$8$$# Default Notify Mechanism : #$$108$$# Address :#$$103$$# Using label/value pairs in templates 205

206 BMC Remedy Action Request System 7.0 To use this template in notifications, the user will have to change it so that it looks like the following example: Login Name : #$$Login Name$$# Password : #$$Password$$# Group List : #$$Group List$$# Full Name : #$$Full Name$$# Default Notify Mechanism : #$$Default Notify Mechanism$$# Address :#$$ Address$$# Add the following core fields to the template: Req Id:#$$Request ID$$# Submitter:#$$Submitter$$# Create Date:#$$Create Date$$# Assigned To:#$$Assigned To$$# Stat:#$$Status$$# ShortDescr:#$$Short Description$$# StatHist:#$$Status History.New.USER$$# Note: Do not use the Request ID to return entries from display or vendor forms in a notification. If you construct a content template using the variable #$$Request ID$$# and use the content template in the Templates tab of notifications on display or vendor forms, the system will not generate errors, but it also will not return the Request IDs. Date formats supported in templates templates support the following date and time formats. Format SHORT Description A numerical date that includes the numerical month, day, and year is displayed (for example, 06/18/04). The order of each component is based on the Regional Options properties in the Control Panel. MEDIUM Longer numerical date description, for example, Jan 12, LONG An alphanumeric date that includes the day of the week, month, day, and year is displayed (for example, Friday, June 18, 2004). The order of each component is based on the Regional Options properties in the Control Panel. FULL Completely specified numerical date description, for example, Tuesday, April 12, 1952 AD. 206 Chapter 6 Using templates

207 Administering BMC Remedy Engine You cannot mix the different locales for short and long formats. So, in the countries where the valid value is mm/dd/yy, dd/mm/yy is not valid and will not work, especially when the dd part is greater than 12. You can see examples of valid date format values when you open Regional Options on your Control Panel for long and short dates. As a result, depending on your locale, 31/01/04 will work as a short date if your locale is set to dd/mm/yy, not mm/dd/yy. The format 31-Jan-04 will not work, but you can use Jan 31, 2004 or January 31, Reserved variables The BMC Remedy Engine uses reserved variables to place the results of executing an . You can use reserved variables in Result and Status templates, but not in Content templates. Reserved variables fall under two main categories: Action information Useful when creating a template that will contain the results of executing the associated action. They can be defined in a Result template along with variables that define the fields of a specific form. The engine will replace these variables with the correct values before the results are returned to the sender of the containing the actions. The following formats are valid: #$$Action.Name$$# The action value, such as Submit, Query, and so on. #$$Action.Number$$# The position of the action within the entire execution list. #$$Action.Form$$# The name of the AR System form involved in this action. #$$Action.Query$$# The qualification (if any) associated with the instruction. (This reserved variable is valid only for User Defined Instruction templates.) These variables are useful when creating a template that will contain the results of executing the associated action. They can be defined in a Result template along with variables that define the fields of a specific form. The execution module will replace these variables with the correct values before the results are returned to the sender of the containing the actions. Using label/value pairs in templates 207

208 BMC Remedy Action Request System 7.0 Status information Used to store the results of system-generated errors. The following formats are valid: #$$ActionStatus.Number$$# The error or warning number. #$$ActionStatus.Type$$# Th e type of e rr or, su ch as S ever e, E r ro r, W arni ng. #$$ActionStatus.Text$$# The message text. #$$ActionStatus.AppendedText$$# The associated appended text. These are also values that you would define in a status template; they are common to all forms. Figure 6-7 displays an that includes these reserved variables for status information. This particular uses the HTML status template found on page 187. Figure 6-7: Reserved variables for status information used in outgoing #$$ActionStatus.Number$# #$$ActionStatus.Type$# #$$ActionStatus.Text$# #$$ActionStatus.Appended Text$# If you want to use specific Status History information in the templates, the following rules apply: You must use the fully qualified status history name, for example: Status-History.New.USER Status-History.New.TIME You can also use numeric values, for example: 15.0.USER Status-History.0.USER 15.New.USER The USER and TIME identifiers are case sensitive. 208 Chapter 6 Using templates

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

210 BMC Remedy Action Request System 7.0 Figure 6-8: AR System Templates form To add a template to the AR System Templates form 1 Create or export your template. 2 Open the AR System Templates form in new mode in BMC Remedy User. 3 Click the Template Information tab. 4 Select the template format (Text or HTML) from the Template Format list. 5 Specify the Encoding so that the BMC Remedy Engine can parse the templates. If you leave the Encoding field empty, the default encoding of the local system is employed. 6 Right-click in the attachment pool, and choose Add from the menu that appears. The Add Attachment dialog box appears. 7 Browse to the template file you want to add and select it. 8 Click Open. The file is added to the list of attachments in the Templates form. You can also click and drag a template to the attachment pool if you are using a Windows system. 210 Chapter 6 Using templates

211 Administering BMC Remedy Engine 9 Select the item in the attachment pool, and click the edit button next to the Template Name field. The name of the attachment is displayed in the Template Name field. For example: template_attachment1.htm. You can edit the file name, for example, to template1.htm. 10 (Optional) Enter a description. It is useful to enter a description indicative of the function of the template. 11 Click Save. The system assigns a Template ID number to the template. (The Template ID field is hidden.) If an HTML template contains a reference to a graphic file, you need to add the graphic file as an attachment. See the following section for information. Adding attachments to HTML templates Use the AR System Attachments form to make sure that a specific attachment is always included with any message that makes use of a specific template. You can add graphics to HTML templates using this form. This is particularly useful for header templates if you want to add a company logo to the header information in your . Note: The BMC Remedy Engine does not support linking your HTML template to a cascading style sheet. To add attachments to HTML templates 1 Open the AR System Templates form in new mode in BMC Remedy User. 2 From the Template Format menu, choose HTML. This activates the buttons on the Template Attachments tab to add attachments to your template. 3 Add a template file as an attachment. 4 Click Save. Adding attachments to HTML templates 211

212 BMC Remedy Action Request System Click the Template Attachments tab. Figure 6-9: AR System Templates form Template Attachments tab Add Attachment button 6 Click the Add Attachment button. The AR System Attachments form opens as shown in the following figure. Figure 6-10: AR System Attachments form for templates Select Template as the attachment Type Attachment pool 7 Select Template from the Type menu. 212 Chapter 6 Using templates

213 Administering BMC Remedy Engine 8 Right-click in the attachment pool, and choose Add from the menu that appears. The Add Attachment dialog box appears. 9 Browse to the file you want to add and select it. 10 Click Open. The file is added to the list of attachments on the AR System Attachments form. If you are using a Windows system, you can also click and drag an attachment to the attachment pool. 11 Select the item in the attachment pool, and click the edit button next to the Attachment Name field. The name of the template attachment is displayed. For example: template_attachment1.htm You can edit the file name, for example, to template1.htm. 12 Click Save. The AR System Attachments form closes. 13 Your attachment will be added to the list in the AR System Templates form. You might need to right-click and select Refresh to see the attachment listed. 14 Click Save in the AR System Templates form. The engine will give the template attachment an ID. (The Attachment ID field is hidden.) Adding a previously saved attachment to your template To add a previously saved attachment to your template 1 In the Template Attachments tab of the AR System Templates form, click the arrow next to the blank field at the bottom of the pane. 2 Select the attachment. 3 Click the Add Existing button. Your attachment is added to the list in the attachment pool. 4 Click Save. Adding attachments to HTML templates 213

214 BMC Remedy Action Request System 7.0 Modifying an attachment To modify an attachment 1 Click the Templates Attachments tab in the AR System Templates form. 2 Select the attachment you want to modify. 3 Click the Modify Attachment button. The AR System Attachments form opens (see Figure 6-10 on page 212). 4 Click Search to locate the attachment. The attachment appears on the attachment list. 5 Modify the attachment as required. You also can modify the Attachment Name. 6 Click Save. Deleting an attachment To delete an attachment 1 Click the Attachments tab in the AR System Templates form. 2 Select the attachment you want to delete. 3 Click Delete Attachment. 4 Click the Refresh Table button to refresh the table in the Attachments tab. The attachment is deleted from the list. 214 Chapter 6 Using templates

215 Administering BMC Remedy Engine Exporting templates with attachments to another server You can export an HTML template from one server and then import the template onto another server. To export templates with attachments to another server 1 Export the HTML template from the AR System Templates form on the source server. 2 Import the template into the AR System Templates form on the target server. 3 Copy the attachments associated with the template from the source server. 4 Manually add the attachments to the template in the AAR System Templates form on the target server. Preparing templates after an upgrade If you have upgraded from BMC Remedy Mail Server (pre-5.1), you might have to modify your existing templates to use the new 7.0 features, for example, the ability to use HTML in your templates. There is, however, a configuration setting that allows you to continue to use your pre-5.1 templates as-is with the 7.0 engine. For more information, see the Use Original Template Format feature described in Advanced incoming mailbox configuration on page 61. To use your old templates after an upgrade to the 7.0 engine, use the following procedure. To prepare templates after an upgrade 1 Verify the following settings in the AR System Mailbox Configuration form: Incoming mailbox is Enabled. Action for your incoming mailbox is set to Parse. Use Original Template Format is set to Yes, if you want to use your original templates for your incoming mailbox as is without using the 7.0 template features. Use Supplied User Information field is set to Yes. Preparing templates after an upgrade 215

216 BMC Remedy Action Request System If only one form is used for submissions, set the Default Workflow Form to that form name. 3 To guarantee that no other form is used for submissions, set Force Default Workflow Form to Yes. 4 If the original templates do not include a user name, user password, or form name, perform one of the following tasks: Modify the template to include these parameters and values. Create a template that includes one or more of these values with a user instruction. For more information, see Overview Sending incoming with user instructions on page 216. Overview Sending incoming with user instructions A good analogy for understanding user instructions is that they are macros for . You can make engine interaction easier for your users by creating custom actions that reduce the need to learn the engine syntax of label/value pairs, variables, and so on. These custom actions are called user instructions. Figure 6-11 provides a sample scenario of how to create user instructions for your user community. 216 Chapter 6 Using templates

217 Administering BMC Remedy Engine Figure 6-11: Overview for using instruction templates 4 User sends with user-defined instructions. 3 Template associated with user instructions. Server Engine 2 Creates user instructions. 5 Results. AR Server Primary Configuration Underlying Database 1 Admin creates and stores templates. User-defined instruction templates automate actions to make it easy to perform common user actions. Like macros, you can create predefined submit and query actions with these instruction templates. Every user instruction must be associated with an template. Templates provide generic layout for similar s that are sent from or into the engine, simplifying engine interactions for users. User Instruction templates enable you to associate a template with an incoming by way of an entry in the AR System User Instruction Templates form. Overview Sending incoming with user instructions 217

218 BMC Remedy Action Request System 7.0 The user sends an containing an Action label and a value for the Action that corresponds to an entry in the AR System User Instruction Templates form. The entry in this form is associated with a template that is then executed. Using this feature, the administrator can set up variable substitutions to be used in an with minimal input from the user; for example, the user can only send an with an Action label/value pair, and a variable value. Creating user instructions involves the following tasks: Step 1 The administrator creates a template, and then adds the template to the AR System Templates form. The user instruction template looks exactly the same as any other template. It can be formatted like any other template (submit, modify, query, and so on). Step 2 Step 3 Step 4 Step 5 The administrator creates a user instruction in the AR System User Instruction Templates form by entering an instruction name into the Instruction field on this form. The administrator associates the template created in step 1 with the user instruction name. The user sends an incoming that contains the user-defined instruction to the BMC Remedy Engine. The contains an Action label and a value corresponding to the valid character string in the Instruction field of the User Instruction Templates form. The value for the variable that appears after the Action label is extracted from the , and the associated template is then executed. As a result, the engine constructs a message according to the template instructions and sends the message to the user. 218 Chapter 6 Using templates

219 Administering BMC Remedy Engine Creating and storing a template for use with user instructions As an administrator, you can use a text editor to define templates by creating a text file with an extension of.arm, and then attaching the.arm file to an entry in the AR System Templates form. To create templates for use with user instructions 1 Use a text editor to define a template, and name the file with an.arm extension. The following example is a template file (IN_Install_AllUrgent.arm) that queries all urgent records in the TestSecurityForm form. Schema: TestSecurityForm Server: polycarp Login: Demo Password: Action: Query Format: Full Header Template: Header_Urgent.html Result Template: Default Content Qualification: 'Status' <= 2 AND 'Impact' = 3 A template can contain one or more instructions. See Creating templates on page 188 for more information. Tip: Test the template by sending to the incoming mailbox and see if it returns the expected results. 2 In BMC Remedy User, open the AR System Templates form in New mode. 3 Attach your IN_Install_AllUrgent.arm file to an entry in the AR System Templates form. Overview Sending incoming with user instructions 219

220 BMC Remedy Action Request System 7.0 Figure 6-12: Storing template 4 Click the Template Attachments tab to add any header, footer, and result templates that are used with your template. 5 Save your changes. Your UrgentRequests template was created and now stored. Creating user instructions After storing your templates, you must associate a name with the User Instruction by creating an entry in the AR System User Instruction Templates form. The User Instruction name will be used as a value for the Action Label in the that is sent by the user to the incoming mailbox. Note: You can associate more than one user instruction with a template containing one or more instructions. 220 Chapter 6 Using templates

221 To create a user instruction Administering BMC Remedy Engine 1 In BMC Remedy User, open the AR System User Instruction Templates form in New mode. 2 Complete the form as follows. (See Figure 6-13 for an example.) a Do not enter a template ID. The system will create the unique ID in the Instruction Template ID field when you save the entry. b From the Template Name menu, select the template that contains that actions you want to associate with the user instruction. Figure 6-13: Creating an entry User Instruction Template form c d You can only use templates that are stored in the AR System Templates form, for example, UrgentRequests. (See Creating and storing a template for use with user instructions on page 219.) To restrict the user instruction to one incoming mailbox, select a mailbox from the Mailbox Name menu. Enter a character string value for the Instruction field. This is the value that will be used to identify this template when used in an incoming , for example, Urgent. Overview Sending incoming with user instructions 221

222 BMC Remedy Action Request System 7.0 Sending a user instruction in an incoming All authorized users can send an to the incoming mailbox of the engine with the name of the User Instruction as the value of the Action Label. To send a user instruction 1 Create a new message in your mail tool. 2 Address the message to the incoming mailbox. 3 Enter the user instruction in your . The user instruction consists of an Action label and value equal to the string defined in the Instruction field in the AR System User Instruction Templates form (Submit). The power of customized user instructions is that your could simply consist of the following text: Action: Submit Your should include any values for the variables if any variables exist in the template associated with the user instruction. 4 Send the . Results of the user instruction The BMC Remedy Engine will then retrieve all records of urgent requests from the AR System server and list them in the , as shown in Figure Chapter 6 Using templates

223 Administering BMC Remedy Engine Figure 6-14: response to user instruction After receiving an incoming , the BMC Remedy Engine processes a user instruction as follows: Retrieves the associated user instruction entry from the AR System User Instruction Templates form and determines which template is associated with the instruction. Retrieves the associated template from the AR System Templates form. Replaces the variables in the template with the values defined by the information in the . Executes the template with substituted values in the incoming . As you can see, templates and user instructions can make it easier for your users to interact with the engine, reducing the need for them to learn the engine syntax. Instead, all they need to do is use the user instruction name as the value of the Action Label. Overview Sending incoming with user instructions 223

224 BMC Remedy Action Request System 7.0 Using variables with user instructions You can also use variables with user instructions. Variables are useful when you need to be able to send different values for the fields to submit an entry. For example, you can create a user instruction that submits information into the User Instruction form. The user might send a user instruction in the following Login:Frank Frontline Password:mypassword Action: Submit!Employee_Name!: [$$Joe Smith$$] The characters between the exclamation marks match the variable name in the template that is associated with the user instruction (Submit). The engine will then: 1 Match the string between exclamation marks in the with the variable name in the template. 2 Retrieve the database name or field ID between the exclamation marks in the template. 3 Substitute the field with that database name with the value sent in the Chapter 6 Using templates

225 Chapter 7 Troubleshooting This chapter contains troubleshooting information. The following topics are provided: Troubleshooting outgoing (page 226) engine architecture (page 227) Error and system status logs (page 229) Debugging options for the BMC Remedy Engine (page 231) Using the Daemon.properties file (page 233) Creating debug batch files (page 242) Fixing common problems with the engine (page 248) Troubleshooting 225

226 BMC Remedy Action Request System 7.0 Troubleshooting outgoing You will find the AR System Messages form especially helpful in troubleshooting outgoing . Performing a search in the form lets you see the current status of messages, for example, if outgoing messages are being processed, if they were sent, or if there was an error, as shown in Figure 7-1. Figure 7-1: Status of messages It is a good practice to keep the AR System Messages form open when using the examples in the chapter, or when you are experimenting with the engine. You can quickly see how the s are being processed by the engine. 226 Chapter 7 Troubleshooting

227 Administering BMC Remedy Engine engine architecture The BMC Remedy Engine consists of multiple modules that run in threads, as shown in Figure 7-2. All the modules of the engine are designed to be thread safe, and to increase speed and scalability. Some modules run in their own threads, while some modules run in the same thread sequentially. For example, the architecture of the engine is designed so that each incoming mailbox uses two threads to process in the message queue that is, the Receiver and Execution modules. But each outgoing mailbox actually uses only one thread running sequentially from the Creator module to the Sender module to format and send outgoing messages. Figure 7-2: Modules and threads in BMC Remedy Engine You can specify various troubleshooting parameters, for example, the queue size of messages or how finely you want to log information within a module. For more information, see Debugging options for the BMC Remedy Engine on page 231 and Using the Daemon.properties file on page engine architecture 227

228 BMC Remedy Action Request System 7.0 The following table describes the purpose of each of the engine modules. Module Monitor Receiver Execution Creator Sender Logging Description and purpose Monitors the mailbox for statistical information such as when the connection dropped and the length of time the connection was down. Runs in separate threads to maximize speed and reliability. Reads incoming mails from the mail server. Creates entries in AR System Messages form. Adds messages to message queue. Parses and executes messages in the message queue. Primarily responsible for creating an based on a template and the data it retrieves from AR System. Monitors the AR System Messages form for outgoing messages. Formats messages to be sent. Runs in a single thread with the Creator module to maximize speed and reliability. It sends formatted messages to the mail server. Logs messages, errors, and warnings to the AR System Errors form or local file. Configuration Maintains configuration information for the system specified in the AR System Mailbox Configuration form and Daemon.properties file. 228 Chapter 7 Troubleshooting

229 Administering BMC Remedy Engine Error and system status logs The AR System Error Logs form (Figure 7-3) stores both error and system status information. This information can be useful in troubleshooting transmission or formatting problems, as well as system environment problems. Figure 7-3: AR System Error Logs form Error logs include information such as: transmission or instruction failures. AR System API errors. Internal engine errors. System status logs include information about: All incoming s. (The is included in the logging message as an attachment.) All outgoing . (The is included in the logging message as an attachment.) Connection status information for servers. Connection status information for the AR System server containing the configuration, logs, and forms. Error and system status logs 229

230 BMC Remedy Action Request System 7.0 Date and time the BMC Remedy Engine was started or stopped. Changes to the configuration of the BMC Remedy Engine. Tip: You can access the Error Logs form from the BMC Remedy User Object List as well as from the Messages form. The Advanced tab in the Messages form includes an Errors tab that, when selected, displays the same log data for the message you are viewing that is also displayed in the Error Logs form. If you click the table field entry under the Errors tab, the entry created in the Error Logs form appears. For more information, see AR System Error Logs form on page transmission or instruction failures When an transmission fails or an instruction cannot be executed, the system generates an error message and stores it in the AR System Error Logs form. Examples of errors include instructions that see a nonexistent form or an invalid server name. In the following sample error message, a form called XYZForm, referenced in two instructions, could not be found on the server either the form name was entered incorrectly, or the form does not exist. Instruction: Submit Instruction Number: 1 Instruction Template: Message Type: Message Number: 303 Message Text: Form does not exist on server Appended Text: XYZForm Instruction: Query Instruction Number: 2 Instruction Template: Message Type: Message Number: 303 Message Text: Form does not exist on server Appended Text: XYZForm 230 Chapter 7 Troubleshooting

231 Administering BMC Remedy Engine AR System API errors The engine will log any AR System API errors that occur while executing instructions in an . For more information, see the Optimizing and Troubleshooting guide. Internal engine errors Any internal problems with the engine itself (for example, if the system runs out of disk space) will be logged. Debugging options for the BMC Remedy Engine The logging.properties file that you use for debugging the engine is usually found in the Java lib directory. For specific issues, see Fixing common problems with the engine on page 248. The following options are available: Setting Definition Global Property Handlers handlers= java.util.logging.consolehandler Sets the places where logs can go. In this example, it has been set to send logs only to the console. Global Property Handlers handlers= java.util.logging.filehandler, java.util.logging.consolehandler Global Logging Level java.util.logging.filehandler. LEVEL = FINER Enables file logging with console logging. Note: On UNIX, all console output is directed to an d.sh_log file under the log s subdirectory of the installation, but file logging can also be switched on. Logging level for the file output. You can set the logging level to Finer in the Java logging.properties file to obtain every log message generated by the system. You can also use the keyword ALL, which means all logs are to be sent to the output. Note: Use this option with care because the contents of the AR System Error Logs form can become very large. Handler Specific Properties java.util.logging.filehandler. pattern = %h/java%u.log File to where logs are made. You can reference the Java documentation on this format, as it is specified by Java 1.4.x logging. Debugging options for the BMC Remedy Engine 231

232 BMC Remedy Action Request System 7.0 Setting Handler Specific Properties java.util.logging.filehandler.limit = Handler Specific Properties java.util.logging.filehandler. count = 1 Handler Specific Properties java.util.logging.filehandler. formatter = java.util.logging.xmlformatter Console Handler Specific Properties java.util.logging.consolehandler. level = INFO Console Handler Specific Properties java.util.logging.consolehandler. formatter = java.util.logging.simpleformatte r Main Application Level com.remedy.arsys. daemon. level = INFO Definition Maximum size of the file. If the system exceeds this length, it will create a new file. Number to start with. This is appended to the end of the file name. Use an XML formatter to format the output, or you can use java.util.logging.simpleformatter with console logging. Logging level for the file output. XML formatter for console logging. Level for the entire engine. This setting for the main application level includes the modules unless you specify otherwise. If a level for one of the outputs is lower than this setting, then this level overrides that level for the given output. In this example, since this level is INFO, the level for the file handler will be ignored and also set to INFO. If the main application level is SEVERE, then only module logs with a level of SEVERE are allowed. You can override this behavior by adding one of these module levels, then specifying that level as FINER, FINE, INFO, or WARNING. This level will be used for all logs originating from that particular module and only that module. If you add more than one module level, then logs for more than one module will be allowed through, and you can set the levels for the different modules independently. 232 Chapter 7 Troubleshooting

233 Administering BMC Remedy Engine Setting Definition Module Levels com.remedy.arsys. daemon. <Module>.level= ConfigurationModule.level=FINER CreatorModule.level=FINER ExecutionModule.level=FINER ReceiverModule.level=FINER SenderModule.level=FINER MonitorModule.level=FINER Levels for application modules. You can specify the logging levels for the various modules independently from the entire engine logging level, for only the modules you are interested in troubleshooting. These application modules allow you to combine main application and module logging. For example, if the main application level is set to INFO and you set the level for the Receiver Module to FINER, then you will see only FINER information in the log for the Receiver module. If there is no entry in the logging.properties file for a particular module, then the system defaults to the application level (that is, INFO). Note: The level for one of the outputs must be at least FINER, such as the ConsoleHandler, to actually see the log. Application levels com.remedy.arsys. daemon. ARSystem Handler.level = WARNING Level for the outputs to the BMC Remedy Error form. You cannot disable this handler as you can with the Console and File. This level could also be overridden if the application level defined previously is higher. Using the Daemon.properties file When the engine is installed, the Daemon.properties file is created in the engine installation directory and is populated with the name of your organization s server, user name, and password. The main purpose of the Daemon.properties file is to identify the AR System server your engine communicates with. Using the Daemon.properties file 233

234 BMC Remedy Action Request System 7.0 Figure 7-4: Sample contents of Daemon.properties file Tip: When discussing the internal components of the BMC Remedy Engine, the term daemon is frequently used. For example, daemon is used to describe background processes launched at start-time, handlers, the use of various threads to carry out different tasks (for example, sending mail, receiving mail, parsing instructions), and so on. In UNIX, these background processes are usually called daemons, whereas for Windows they are called services. Following the UNIX convention, the file you use to set parameters for the engine is called Daemon.properties. For the most part, you should think of the BMC Remedy Engine as synonymous with the daemon. To use the Daemon.properties file, see Fixing common problems with the engine on page Chapter 7 Troubleshooting

235 Updating the Daemon.properties file Administering BMC Remedy Engine If your environment changes for example, if you need to change a server name or a TCP port this file must be updated. The following procedure explains how to update the Daemon.properties file. To update the Daemon.properties file 1 Open a command prompt. 2 Change directories to the AR System installation directory, and enter the following command: For Windows: <JRE_install_path>\java -cp daemon.jar;arapi70.jar;arutil70.jar;activation.jar;mail.jar; imap.jar;smtp.jar;pop3.jar; com.remedy.arsys. daemon. daemon <parameters> where <JRE_install_path> is the path of your Java Runtime Environment (JRE) installation and <parameters> represent the parameters you specify to update the file. For UNIX: <JRE_install_path>/java -cp daemon.jar:arapi70.jar:arutil70.jar:activation.jar:mail.jar:imap.jar:smtp.jar:pop3.jar com.remedy.arsys. daemon. daemon <parameters> The UNIX classpath requires colons, not semicolons. Note: To use this command, make sure that you properly set the LD_LIBRARY_PATH path for all UNIX platforms. Table 7-1 lists the available parameters: Table 7-1: engine startup parameters Parameter Description -s Server where the forms (and the configuration information) are located. -p AR System Application Service password. The engine uses the same password as that supplied in BMC Remedy Administrator under File > Server Information > Connection Settings > Application Service Password. Using the Daemon.properties file 235

236 BMC Remedy Action Request System 7.0 Table 7-1: engine startup parameters Parameter Description -t TCP port for the server to which the engine should connect. -r RPC number of the server to which the engine should be connected. This parameter can be useful if you want to connect to a private server. This can enhance performance if you expect a high volume of mail. -l Language to be used. (The default is C.) -d Directory where the Daemon.properties file is located. If this parameter is not supplied, the system assumes that this file is stored in the same directory as the daemon.jar file. -i Time interval (in minutes) to use when checking the server for configuration updates (modifications to records in the Mailbox Configuration form). The default is 30 minutes. -m Monitor module interval (in minutes) to wait before trying to start the engine again. The default is 30 minutes. When the AR System server is not available, it tries to restart the system for every 30 minutes by default. -o MAPI sent folder where sent mail should be stored. Performance and configuration settings The Daemon.properties file also lets you specify properties you can use to enhance the performance of the engine. For specific troubleshooting issues, see Fixing common problems with the engine on page Chapter 7 Troubleshooting

237 Administering BMC Remedy Engine The following properties are available in the Daemon.properties file to adjust the default performance and configuration of the engine. After adding these new settings, you must stop and restart the engine to implement them. Settings com.remedy.arsys. daemon. AdditionalMailHeaders=X-Loop- Detect com.remedy.arsys. daemon. ARDATE= com.remedy.arsys. daemon. ARDATEONLY= com.remedy.arsys. daemon. ARTIMEONLY= com.remedy.arsys. daemon. ChunkSize=100 com.remedy.arsys. daemon. CommaValidAddressSeparator= true com.remedy.arsys. daemon. Exchange-Wait-Time=1 com.remedy.arsys. daemon. ExecutionModule.level=Fine Definitions This setting lets you specify additional headers. The additional headers are to be separated by comma. This setting lets you specify the date and time format used by the engine for parsing date and time strings. MMMMM dd, yyyy HH:mm:ss z is equivalent to September 21, :08:56 PDT. This setting lets you specify the time format used by the engine for parsing date strings. MMMMM dd, yyyy is equivalent to September 21, This setting lets you specify the time format used by the engine for parsing time strings. HH:mm:ss z is equivalent to 12:08:56 PDT. This setting lets you specify the set size of entries to return when the engine makes a call to the AR System server. The default chunk size of entries returned is set to 100. Specifies whether you can use a comma as a separator when entering multiple addresses in the To and CC lines. By default, this property is set to true. Set this property to false if user names in mail server contains commas. (This is usually needed only when using MAPI protocol.) For example, if a name is stored on the mail server as follows: Smith, John and Cho, Rick You would need to use semicolons to separate the addresses: Smith, John; Cho, Rick This setting specifies the amount of time the thread waits before processing the next message when there are more messages to be processed. The unit of time is milliseconds. This setting lets you add new log messages for logging instructions and instruction parameters. Using the Daemon.properties file 237

238 BMC Remedy Action Request System 7.0 Settings com.remedy.arsys. daemon. FetchUserGroupInfoOnDemand= false com.remedy.arsys. daemon. IncomingConnectionRecycleSize= 100 com.remedy.arsys. daemon. IncomingMessagesQueueSize=100 com.remedy.arsys. daemon. instructioncachesize=20 com.remedy.arsys. daemon. Mailboxes= Definitions This setting lets you specify whether to fetch the user and group information about demand as opposed to loading all users and groups at startup. The default value for this property is false. If there are many users or groups, you might want to set this property to true to reduce the startup time for . This setting lets you change the default number of how many messages the engine receives before the connection is closed and reopened. By default, the connection is closed and reopened for every 100 messages. In the 5.1 and releases of the engine, the connection with mail server was closed only after reading all incoming messages. As a result, if the engine crashed or hung before the connection was closed, the messages marked for deletion might not be deleted from the mail server. This setting lets you define message queue size. Receiver module writes messages to the queue and Execution module reads messages from this queue to parse and execute. Receiver module still writes messages to server in AR System Messages form, but the Execution module reads the message from the message queue instead of from the server. This reduces the traffic to the AR System server and improves the performance. The default message queue size is set to 100. This setting lets specify the size of the cache used for storing instructions, to improve performance. The default setting keeps 20 instructions in cache. If there are 20 instructions and another is added, the oldest instruction is removed. If any changes are made to the Instructions form, the instruction cache is flushed based on the configuration Interval setting. If you run multiple engines for a single server, this setting specifies which mailboxes this engine should process. The value should contain comma-separated mailbox names. If the value is empty, the engine processes all of the mailboxes configured for the server. If the value is not empty, the engine processes the specified mailboxes only. 238 Chapter 7 Troubleshooting

239 Administering BMC Remedy Engine Settings com.remedy.arsys. daemon. MailboxPollingUnitIsMinutes= true Definitions This setting lets you change the polling interval value from minutes (as configured in the AR System Configuration form) to seconds. Setting the value to false means interpret the polling number as seconds, for example, com.remedy.arsys. daemon. MailboxPollingUnitIsMinutes=false. Note: Whatever measure of unit you select applies to all enabled configured mailboxes. com.remedy.arsys. daemon. MaxAttachSize com.remedy.arsys. daemon. MaxAttachSizeFileExtensions com.remedy.arsys. daemon. Monitor=30 com.remedy.arsys. daemon. NumberOfSenderThreads=1 com.remedy.arsys. daemon. OutgoingMessagesQueueSize= 100 Together, these settings let you specify the maximum size of specific attachment types that you will allow in an message. For example, to set the maximum size of.doc,.pdf, and.xls attachments to bytes (1MB), you would use the following syntax: com.remedy.arsys. daemon.maxattachsize= com.remedy.arsys. daemon.maxattachsizefileextens ions=doc,pdf,xls File extensions that are not defined have no size limit. with attachments that exceed this maximum size are logged to the AR System Error Logs form. Extension types in MaxAttachSizeFileExtensions are separated with commas. Optionally, you can then create workflow against this form to process these messages separately. This setting lets you specify the interval between checks to see if all the threads are functioning properly. This interval is measured in minutes, and like the configuration interval, the default value is 30. If the Monitoring system detects that a thread has failed, then it restarts the thread. This setting lets you specify the number of sender threads per outgoing mailbox that the daemon uses. The optimum number of threads depends on many factors including the number of mailboxes, hardware of the machine, and so on. The default value for this setting is 1. This setting lets you specify the size of the queue that the daemon maintains for the outgoing mails. The default size of outgoing message queue size is set to 100. The optimum number of message queue size to be specified depends on the load on the daemon. Using the Daemon.properties file 239

240 BMC Remedy Action Request System 7.0 Settings com.remedy.arsys. daemon. OutgoingConnectionRecycleSize= 100 com.remedy.arsys. daemon. RMIPORT=1099 com.remedy.arsys. daemon. SaveSentItem=True com.remedy.arsys. daemon. securitycachesize=20 com.remedy.arsys. daemon. Send SetSize=100 com.remedy.arsys. daemon. <server_name>.authentication com.remedy.arsys. daemon. <server_name>.interval=30 com.remedy.arsys. daemon. <server_name>.language=en_us com.remedy.arsys. daemon. <server_name>.rpc=0 Definitions This setting lets you define the number of messages to process before closing the connection to the mail server. This action is performed to make sure that memory is properly released. The default setting is 100 messages. This setting lets you specify the port for RMI (remote method invocation). This feature is used with the AdminAgent.jar file to stop, suspend, resume, or change logging to the engine. This setting lets you keep the sent items in the Messages form. Set to False if you want to delete the sent items from the Messages form. This setting lets you specify how many security keys are kept in cache. The default setting keeps 20 security keys in cache. If there are 20 keys and another is added, the oldest key is removed. If any changes are made to the Security form, the cache is flushed based on the configuration Interval setting. This setting lets you specify how many outgoing s to query at a time. The default size of outgoing s is set to 100. This setting lets you specify a string if your AR System server requires authentication information before handling requests. This setting lets you define the time interval (in minutes) to use when checking the server for configuration updates (for example, if you have modified records in the Mailbox Configuration form) or updates to templates (for example, if you modified templates in the Templates form). The default is 30 minutes. For example, to set the interval to 5 minutes, you would use the following syntax: com.remedy.arsys. daemon.<server_name>.interva l=5 This setting lets you specify what language to use in the engine, for example, com.remedy.arsys. daemon. <server_name>.language=en_us. This setting lets you specify what RPC port number the AR System server uses if you have configured a private server to use with the engine. 240 Chapter 7 Troubleshooting

241 Administering BMC Remedy Engine Settings com.remedy.arsys. daemon. <server_name>.tcp=0 com.remedy.arsys. daemon. Servers com.remedy.arsys. daemon. SortMessages=false com.remedy.arsys. daemon. StoreInstructions=true com.remedy.arsys. daemon. templatecachesize=20 com.remedy.arsys. daemon. UseNameIfNo Address=true com.remedy.arsys. daemon. UserChunkSize=5000 Definitions This setting lets you specify what TCP port number the AR System uses if your AR System server is not using Portmapper. This setting lets you specify the AR System server that the engine interacts with. This setting lets you specify if messages with a higher priority setting are processed first. The default setting is false. This setting lets you store instructions and instruction parameters in the AR System server. Setting this option to true lets you leave data in the Instructions form and the Parameters form for troubleshooting purposes. If you choose the true option, you must remove this information explicitly. Execution module in the engine handles both the parsing and execution of messages. There will be one message queue created for each Incoming mailbox. By default, instructions are not stored in the server. This setting lets you specify how many templates are kept in cache, to improve performance. The default setting keeps 20 templates in cache. If there are 20 templates and another is added, the oldest template is removed. If any changes are made to the Templates form, the cache is flushed based on the configuration Interval setting. This setting lets you specify how the engine behaves when the To, CC, or BCC field has a display name instead of an address. If this property is true (the default), the display names that do not have associated address are not removed from the To, CC or BCC fields. If this setting is false, the display names that do not have associated addresses are removed from the To, CC or BCC fields. This setting lets you specify the number of users (records from the User form) to retrieve from the AR System server at one time, to improve performance. The default chunk size of users returned is set to Using the Daemon.properties file 241

242 BMC Remedy Action Request System 7.0 Creating debug batch files Creating a debug batch file using the -Dmail.debug=true debug mode can help resolve issues that might not show up in the error log. You accomplish this by setting the debug mode for the Java process that runs the engine. You might find this procedure useful for debugging the engine in contrast to using the AR System Error Logs form. The contents of the AR System Error Logs form can become very large. Tip: If you are having problems with the engine, BMC Remedy Customer Support frequently will ask you to use to -Dmail.debug=true debug mode to troubleshoot the issue. Windows Debugging the engine To enable the -Dmail.debug=true debug mode option for Windows, perform the following steps: To debug the Windows engine 1 Edit the start.bat file and add the -Dmail.debug=true option after "%JavaPath%\java": "%JavaPath%\java" -Dmail.debug=true -cp daemon.jar;arapi70.jar;arutil70.jar;activation.jar;mail.jar;imap.jar;smtp.jar;pop3.jar;armapi70.jar com.remedy.arsys. daemon. daemon The default location of the start.bat file is C:\Program Files\AR System\AR . 2 Save the batch file as another name, for example, debug.bat. 3 Make sure that the BMC Remedy Engine service is stopped in the services window. 4 Open a command prompt, change the directory to the location of the AR System install directory, and run the new batch file. This batch file will add debug information to the screen when is started from a command prompt. You can also have the output go to a file by adding > c:\temp\debug.out to the end of the previous Java statement. 242 Chapter 7 Troubleshooting

243 Sample debug log The contents of a sample debug log follow. Administering BMC Remedy Engine C:\Program Files\AR System\AR >echo off Application has started Version: Using JRE: 1.4.1_02 Checking connection to server: polycarp... loaded library Successfully connected. DEBUG: JavaMail version 1.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.4.1_02\lib\javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / daemon.jar!/meta-inf/javamail.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR / daemon.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / imap.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /imap.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / smtp.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /smtp.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / pop3.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /pop3.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: /META-INF/ javamail.default.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com.remedy.mail.mapi.mapitransport=javax.mail.provider[transport,map itransport,com.remedy.mail.mapi.mapitransport,[email protected]], com.remedy.mail.mapi.mapistore=javax.mail.provider[store,mapistore,co m.remedy.mail.mapi.mapistore,[email protected]], com.sun.mail.smtp.smtptransport=javax.mail.provider[transport,smtp,co m.sun.mail.smtp.smtptransport,sun Microsystems, Inc], com.sun.mail.imap.imapstore=javax.mail.provider[store,imap,com.sun.ma il.imap.imapstore,sun Microsystems, Inc], com.sun.mail.pop3.pop3store=javax.mail.provider[store,pop3,com.sun.ma il.pop3.pop3store,sun Microsystems, Inc]} Creating debug batch files 243

244 BMC Remedy Action Request System 7.0 DEBUG: Providers Listed By Protocol: {imap=javax.mail.provider[store,imap,com.sun.mail.imap.imapstore,sun Microsystems, Inc], mapistore=javax.mail.provider[store,mapistore,com.remedy.mail.mapi.ma mapitransport=javax.mail.provider[transport,mapitransport,com.remedy. pop3=javax.mail.provider[store,pop3,com.sun.mail.pop3.pop3store,sun Microsystems, Inc], smtp=javax.mail.provider[transport,smtp,com.sun.mail.smtp.smtptranspo rt,sun Microsystems, Inc]} DEBUG: successfully loaded resource: /META-INF/ javamail.default.address.map DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / smtp.jar!/meta-inf/javamail.address.map DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /smtp.jar!/META-INF/javamail.address.map DEBUG: java.io.filenotfoundexception: C:\Program Files\Java\j2re1.4.1_02\lib\javamail.address.map (The system cannot find the file specified) DEBUG: JavaMail version 1.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.4.1_02\lib\javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / daemon.jar!/meta-inf/javamail.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR / daemon.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / imap.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /imap.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / smtp.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /smtp.jar!/META-INF/javamail.providers DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / pop3.jar!/meta-inf/javamail.providers DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /pop3.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: /META-INF/ javamail.default.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com.remedy.mail.mapi.mapitransport=javax.mail.provider[transport,map com.remedy.mail.mapi.mapistore=javax.mail.provider[store,mapistore,co com.sun.mail.smtp.smtptransport=javax.mail.provider[transport,smtp,co m.sun.mail.smtp.smtptransport,sun Microsystems, Inc], com.sun.mail.imap.imapstore=javax.mail.provider[store,imap,com.sun.ma il.imap.imapstore,sun Microsystems, Inc], com.sun.mail.pop3.pop3store=javax.mail.provider[store,pop3,com.sun.ma il.pop3.pop3store,sun Microsystems, Inc]} 244 Chapter 7 Troubleshooting

245 Administering BMC Remedy Engine DEBUG: Providers Listed By Protocol: {imap=javax.mail.provider[store,imap,com.sun.mail.imap.imapstore,sun Microsystems, Inc], mapistore=javax.mail.provider[store,mapistore,com.remedy.mail.mapi.ma mapitransport=javax.mail.provider[transport,mapitransport,com.remedy. pop3=javax.mail.provider[store,pop3,com.sun.mail.pop3.pop3store,sun Microsy stems, Inc], smtp=javax.mail.provider[transport,smtp,com.sun.mail.smtp.smtptranspo rt,sun Microsystems, Inc]} DEBUG: successfully loaded resource: /META-INF/ javamail.default.address.map DEBUG: URL jar:file:/c:/program%20files/ar%20system/ar / smtp.jar!/meta-inf/javamail.address.map DEBUG: successfully loaded resource: jar:file:/c:/program%20files/ AR%20System/AR /smtp.jar!/META-INF/javamail.address.map DEBUG: java.io.filenotfoundexception: C:\Program Files\Java\j2re1.4.1_02\lib\javamail.address.map (The system cannot find the file specified) DEBUG: getprovider() returning javax.mail.provider[store,pop3,com.sun.mail.pop3.pop3store,sun Microsy stems, Inc] POP3: connecting to host "essmail2", port 110 S: +OK Microsoft Exchange 2000 POP3 server version (essmail2.eng.remedy.com) ready. C: USER stamps3 S: +OK C: PASS password S: +OK User successfully logged on. C: STAT S: +OK 0 0 C: QUIT S: +OK Microsoft Exchange 2000 POP3 server version signing off. UNIX Debugging the engine To enable the -Dmail.debug=true debug mode option for UNIX, perform the following steps: To debug the UNIX engine 1 Open the d.sh script. 2 Add the following option to the line that starts the Java process in the d.sh script: -Dmail.debug=true Creating debug batch files 245

246 BMC Remedy Action Request System Edit the d.sh script from: exec ${JAVA_BIN}/java -Djava.library.path=${InstallPath} -cp ${CP_PATH} com.remedy.arsys. daemon. daemon -d ${InstallPath} >${LogFile} 2>&1 To the following: exec${java_bin}/java -Djava.library.path=${InstallPath} -Dmail.debug=true -cp ${CP_PATH} com.remedy.arsys. daemon. daemon -d ${InstallPath} >${LogFile} 2>&1 4 Stop and start the engine. 246 Chapter 7 Troubleshooting

247 Example of outgoing using SMTP Administering BMC Remedy Engine The contents of a sample debug log for outgoing follow. DEBUG: getprovider() returning javax.mail.provider[transport,smtp,com.sun.mail.smtp.smtptransport,su n Microsystems, Inc] DEBUG SMTP: useehlo true, useauth true DEBUG: SMTPTransport trying to connect to host "cruiser", port 25 DEBUG SMTP RCVD: 220 cruiser.remedy.com ESMTP Sendmail Sun/ ; Mon, 10 Feb :19: (PST) DEBUG: SMTPTransport connected to host "cruiser", port: 25 DEBUG SMTP SENT: EHLO cruiser.remedy.com DEBUG SMTP RCVD: 250-cruiser.remedy.com Hello cruiser.remedy.com [ ], pleased to meet you 250-ENHANCEDSTATUSCODES 250-EXPN 250-VERB 250-8BITMIME 250-SIZE 250-DSN 250-ONEX 250-ETRN 250-XUSR 250 HELP DEBUG SMTP Found extension "ENHANCEDSTATUSCODES", arg "" DEBUG SMTP Found extension "EXPN", arg "" DEBUG SMTP Found extension "VERB", arg "" DEBUG SMTP Found extension "8BITMIME", arg "" DEBUG SMTP Found extension "SIZE", arg "" DEBUG SMTP Found extension "DSN", arg "" DEBUG SMTP Found extension "ONEX", arg "" DEBUG SMTP Found extension "ETRN", arg "" DEBUG SMTP Found extension "XUSR", arg "" DEBUG SMTP Found extension "HELP", arg "" DEBUG SMTP: use8bit false DEBUG SMTP SENT: MAIL FROM: DEBUG SMTP RCVD: Sender ok DEBUG SMTP SENT: RCPT TO: DEBUG SMTP RCVD: Recipient ok Verified Addresses [email protected] DEBUG SMTP SENT: DATA DEBUG SMTP RCVD: 354 Enter mail, end with "." on a line by itself DEBUG SMTP SENT: DEBUG SMTP RCVD: h1akjzh09819 Message accepted for delivery Creating debug batch files 247

248 BMC Remedy Action Request System 7.0 Example of incoming using MBOX The contents of a sample debug log for incoming follow. You can see the lock file get created the file is read, then saved, and the lock is removed. # tail -f d.sh_log DEBUG: java.io.filenotfoundexception: /usr/java1.4.1/j2se/jre/lib/ javamail.address.map (No such file or directory) DEBUG: getprovider() returning javax.mail.provider[store,mbox,gnu.mail.providers.mbox.mboxstore,dog@ gnu.org] mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock Fixing common problems with the engine Configuring mailboxes This section describes how to diagnose and solve some problems you might encounter with the BMC Remedy Engine. The most common issue reported is that the engine is not receiving or sending any new s. The engine can be a powerful and useful tool if configured and used correctly. A common problem that users experience with the engine is that they cannot send or receive . A straightforward way to troubleshoot this problem is to verify that you have properly configured your incoming and outgoing mailboxes. 248 Chapter 7 Troubleshooting

249 Testing your incoming mailbox Administering BMC Remedy Engine If you were unable to test your incoming mailbox configuration successfully, verify the following conditions: The engine is running. The mail server is running. The Status field of the mailbox should be set to Enabled. The account used by the Incoming Mailbox is a valid account on the mail server (POP3/IMAP4) or the Exchange profile specified for this mailbox is accessible on the system the engine is running on (MAPI). Note: By default, the engine service is launched as the local system account. However, if you elected to configure a MAPI mailbox during installation, you must change the login information (in the Services control panel) for the engine service from the local system account to the appropriate account. The port number in the mailbox entry is the proper port number for communicating with your mail server. You have entered the right password for the account in the Incoming Mailbox Basic configuration tab (POP3/IMAP4). The address you chose to send the message to was the proper address for directing to the account (POP3/IMAP4) or profile (MAPI) specified in the Incoming Mailbox. You have waited for a period of time not less than that indicated by the Polling Interval before checking the AR System Messages form for your message. Note: Any changes you make to your mailbox in an effort to troubleshoot possible configuration problems, might not be immediately recognized by the engine. For more information, see Changing the form entry interval time on page 76. Fixing common problems with the engine 249

250 BMC Remedy Action Request System 7.0 Testing your outgoing mailbox If you were unable to test your outgoing mailbox configuration successfully, verify the following conditions: The engine is running. The mail server is running. The Status field of the mailbox should be set to Enabled. Determine if the mail server requires authentication in order for messages to be sent. If your mail server requires authentication, then you must make sure that you have provided valid account information for this mail server in the Basic Configuration tab for this mailbox (SMTP) or the name of a valid Exchange profile (MAPI). The port number in the mailbox entry is the proper port number for communicating with your mail server. You have entered the right password for the account in the Outgoing Mailbox Basic configuration tab (SMTP) or you have logged in to the system as the domain user account that has permission to use the MS Exchange profile (MAPI). You have waited for a period of time not less than that indicated by the Polling Interval before checking the AR System Messages form to see if your message was sent. Note: Any changes you make to your mailbox in an effort to troubleshoot possible configuration problems, might not be immediately recognized by the engine. For more information, see Changing the form entry interval time on page 76. Logging problems with the engine The reason you have problems sending or receiving can depend on when the error occurs and the frequency at which it occurs. The best way to troubleshoot these problems is by creating log files and examining your console output. 250 Chapter 7 Troubleshooting

251 To use the engine logs and console output Administering BMC Remedy Engine 1 Stop the engine, and then re-start the engine from the command line using debug mode. For more information, see Creating debug batch files on page Examine the AR System Error Logs form. The daemon always uses the AR System Error Logs form when logging errors and warnings. This should be the first place any administrator looks to identify an issue. 3 Consult the console output to access more details, such as stack traces and the exact exceptions thrown. The location of the console output depends on how the application is executed and on which system. (Recommended) For both Windows and UNIX, when the engine is started from the command line, all console output is piped to the open console window. This is the quickest and easiest way to identify an issue because you can see where the output actually occurred and you can trace any errors. When the daemon is executed on Windows as a service, the output is located under the logs subdirectory of the engine installation (by default, c:\program Files\AR System\AR \Logs). You might find two files: stdout.log and stderr.log. Both files contain the console output, but stdout.log contains normal output, such as the startup information and possible debug output, while stderr.log contains any errors generated while the application was running. On any UNIX system, you can view the console output under the logs sub-directory of the engine installation, as you can with Windows, but in UNIX, the console output is stored in just one file called d.sh_log. 4 Make sure that console logging is turned on in the logging.properties file, located in the <Java_install>/lib directory. 5 Enable the console output with the following handler property: handlers= java.util.logging.consolehandler 6 Set the level for console logging. Usually, the level is set to INFO by default, which locates most problems with the engine. You set this level with the following line: java.util.logging.consolehandler.level = INFO Fixing common problems with the engine 251

252 BMC Remedy Action Request System Set the level for the entire application. Make sure that the following two lines are located in the logging.properties file: com.remedy.arsys. daemon.level = INFO com.remedy.arsys. daemon.arsystemhandler.level = INFO The first line sets the level for the entire application; the second line sets the level for logging to the AR System Error Logs form. The level for the form logging should never be set lower than this. Otherwise, the table will fill up very quickly and use unnecessary space. Defining a heap size for the engine Sometimes you see out of memory errors if you run out of heap space. You should set your heap size according to your memory needs. BMC Remedy cannot recommend exact settings; try modifying the minimum and maximum settings, and then stopping and restarting the engine. You might see dramatic improvements in performance. Windows Setting the heap size You can modify the registry as needed for the engine service for minimum and maximum heap size. For Java 1.4.x, the options to use are -ms<size> or -Xms<size> for the minimum, and -mx<size> or -Xmx<size> for the maximum. For example, you could enter: java -ms50m -mx256m myclass To add a maximum heap size, you must add the following to the registry: Key: HKLM\SYSTEM\CurrentControlSet\Services\Remedy Engine\Parameters Tag: JVM Option Number 2 Value: -xm<size> You must also modify the JVM Option Count from 2 to 3. UNIX Setting the heap size For Java 1.4.x, the options to use are -Xms<size> for the minimum, and -Xmx<size> for the maximum. For example, you could insert the following line into the d.sh file: java -Xms50m -Xmx256m com.remedy.arsys. daemon. daemon 252 Chapter 7 Troubleshooting

253 Administering BMC Remedy Engine Troubleshooting startup issues After installing the new engine, users might find that has not been sent or received. In this situation, new , ready to be sent, has the status set to Yes, but the status does not change to Error or Sent. This is a common problem with the engine and is usually easy to fix. The following troubleshooting sections describe three common scenarios and their possible solutions. Identifying invalid application service passwords When viewing the AR System Error Logs form, you might not find any errors. Further, it might seem that the daemon is not working at all. In this situation, the most likely problem is that the engine is not able to communicate with the AR System server. You might have supplied an invalid application service password during installation. To determine the use of an invalid password 1 Use the debug mode to start the engine from the command line. For more information, see Creating debug batch files on page Review the console output and note the JRE version used by the engine. The JRE version should be 1.4.1_01 or higher. Typically, a functioning daemon outputs the following status information: C:\Program Files\AR System\AR >echo off Application has started Version: Using JRE: 1.4.1_02 Checking connection to server: polycarp... loaded library Successfully connected. From this console output, you can see that the daemon is using the correct JRE version, 1.4.1_02. Note: Installing Java version 1.4.1_00 (or later) is mandatory for installation of the engine to finish successfully. If you do not have the correct Java version, the installation program exits and you are reminded to install Java 1.4.1_00 (or later) before you try installing again. Fixing common problems with the engine 253

254 BMC Remedy Action Request System 7.0 The console output also shows that the daemon has loaded the AR System API library correctly. If the daemon was unable to connect to the AR System server, you might see the following error: Application has started Version: Using JRE: 1.4.1_02 loaded library 8-Apr :06:52 AM com.remedy.arsys. daemon.loggingmodule dowork SEVERE: Invalid password for an existing user If you see this, the Application Service Password you supplied during installation is incorrect. To fix the problem, you must edit the startup script. 3 Open the startup script file in a text editor on Windows, Start.bat, on UNIX, d.sh. 4 Append the following statement to the end of the line that starts the engine: -s <ar_system_server_name> -p <application_service_password> 5 Execute the script, which updates the system with the correct password by applying the changes to the Daemon.properties file. 6 Edit the script again, remove this addition, and restart your system. Removing invalid application service passwords Use one of the following methods to remove the invalid password: To remove an invalid password using BMC Remedy Administrator 1 Log in to BMC Remedy Administrator. 2 Select the server on which the engine is installed. 3 Open the Server Information window. 4 Click the Connection Settings tab. 5 If there is a password in the Application Service Password field, remove it. 6 Save your changes. 7 Stop and start the AR System server. 8 Stop and re-start the engine. After the password is removed, the console output should show that the daemon has successfully connected to the AR System server with no errors. 254 Chapter 7 Troubleshooting

255 Administering BMC Remedy Engine To remove an invalid password using the Daemon.properties file 1 Open the Daemon.properties file, usually located in the engine installation directory. 2 Locate the following line: com.remedy.arsys. daemon.<ar_system_server_name>.password=<applic ation_service_password> It might look like the following example: com.remedy.arsys. daemon.polycarp.password=zb1<v+%whamgwobh7mzl_~ L}7+isE 3 Change its contents to the following text: com.remedy.arsys. daemon.polycarp.password= 4 Stop and start the AR System server. 5 Stop and re-start the engine. After the password is removed, the console output should show that the daemon has successfully connected to the AR System server with no errors. Determining if the wrong AR System server is specified Another common problem is that you specified the wrong AR System server name when you installed the engine. You can fix this problem by executing a search and replace on the contents of the Daemon.properties file. To determine if a wrong AR System server is specified 1 Open the Daemon.properties file. 2 Replace all references to the incorrect server name with the correct server name. The search and replace functionality is required, since the file uses the server name in several places. 3 Check the connection to the AR System Server if you are using a specific TCP port or RPC number. Update these references as well in the Daemon.properties file: com.remedy.arsys. daemon.<ar_system_server_name>.tcp=4040 com.remedy.arsys. daemon.<ar_system_server_name>.rpc=0 Fixing common problems with the engine 255

256 BMC Remedy Action Request System 7.0 Remember that the <ar_system_server_name> tag is the name of the server against which the engine is running and could be an alias like production (for example, com.remedy.arsys. daemon.production.tcp=4040). 4 Examine the AR System Mailbox Configuration forms to make sure that you have configured your mailboxes correctly. Check to make sure that you have not disabled any of the mailboxes. 5 Save your changes to the Daemon.properties file. 6 Stop and re-start the engine. The console output should show that the daemon has successfully connected to the AR System server with no errors. Determining problems with the mail server If the daemon is able to connect to the AR System server, but incoming is not logged and outgoing s have not been sent, errors should be logged in the form and on the console, assuming that console logging has been enabled properly. Some error messages you might encounter with the mailbox include: Unknown Host Exception Authentication Failed Exception Connect Exceptions, such as Connection Refused In these situations, the problem is usually because the mailbox has not been configured properly in the AR System Mailbox Configuration form. The connection exception error might also occur if the server (such as MS Exchange) is too busy to handle the connection or you have connected too many times in a given time period (due to a DOS attack). Use the following procedure to check the mail server. To determine problems with the mail server 1 Log in to BMC Remedy User. 2 Open the AR System Mailbox Configuration form in Search mode. 3 Open the entries for both the incoming and outgoing mailboxes. 4 Check the server name. Confirm that you can ping or connect from the system by using an client, such as MS Express. 256 Chapter 7 Troubleshooting

257 Administering BMC Remedy Engine 5 Confirm the server supports the protocol you supplied, for example, MAPI or SMTP. 6 Confirm the server port. 7 If you are unsure, click the Set Server Port button to force this value to be the default for that protocol. Each protocol has a different default value, unless the mail server has been configured differently. If this is the case, check the value with your server administrator. 8 Check the User Name and Password. Retype them if necessary. Windows Fixing MAPI transport problems When using the engine on Windows, your primary server is MS Exchange, and you have specified MAPI as the protocol to use, you might encounter the following MAPI transport error when starting the daemon: Application has started Version: Using 1.4.1_02 loaded library 8-Apr :00:36 PM javax.mail.session getservice SEVERE: mapitransport javax.mail.nosuchproviderexception: mapitransport at javax.mail.session.getservice(session.java:760) at javax.mail.session.gettransport(session.java:685) at javax.mail.session.gettransport(session.java:628) at javax.mail.session.gettransport(session.java:608) at com.remedy.arsys. daemon.sendermodule.opentransport (SenderModule.java:103) at com.remedy.arsys. daemon.creatormodule.dowork (CreatorModule.java:323) at com.remedy.arsys. daemon.threadbase.run (ThreadBase.java:259) at java.lang.thread.run(thread.java:536) You typically see this problem when the JavaMail System does not know what transport setting to use for MAPI, and the library cannot locate the correct class to use for MAPI. Fixing common problems with the engine 257

258 BMC Remedy Action Request System 7.0 To fix the MAPI transport problem (Windows) 1 Locate the javamail.providers file in the lib directory of the JRE installation. This is the same location as the logging.properties file. You can create this file if necessary. 2 On the first line, verify (or add) the following text: protocol=mapistore; type=store; class=com.remedy.mail.mapi.mapistore; [email protected]; 3 On the second line, verify (or add) the following text: protocol=mapitransport; type=transport; class=com.remedy.mail.mapi.mapitransport; [email protected]; 4 Stop and re-start the engine. These settings make sure that the JavaMail System uses the class created to support MAPI for both incoming and outgoing mailboxes. UNIX Fixing MAPI transport problems On UNIX, where you might be using MBOX as your protocol, you will see a similar error except that the mapitransport string will be labeled mbox. You fix this problem in exactly the same way as on Windows. To fix the MAPI transport problem (UNIX) 1 Locate the javamail.providers file in the lib directory of the JRE installation. This is the same location as the logging.properties file. You can create this file if necessary. 2 On the second line, verify (or add) the following to the javamail.providers file: protocol=mbox; type=store; class=gnu.mail.providers.mbox.mboxstore; [email protected]; 3 Stop and re-start the engine. WARNING: The MBOX store uses the dotlocking mechanism, which is compatible with most UNIX MUAs and MTAs, to synchronize concurrent access to the mailbox. You might experience data loss if you use non-dotlocking mail agents, and mail agents and the MBOX provider access the same mailboxes at the same time. 258 Chapter 7 Troubleshooting

259 Stopping and starting the AR System server Administering BMC Remedy Engine If you stop the AR System, the daemon stops all the appropriate threads until the AR System server is started again. During this time, the daemon stops all the threads monitoring this AR System server for new outgoing s and also all the associated mailboxes for new incoming s. After these threads have been stopped, the daemon goes to sleep for the configured time period (the default setting is 30 minutes). When that time expires, the daemon then checks if the AR System server is running and takes one of two actions based on the results: If the AR System server is still down, the daemon will go back to sleep for the configured time period. If the AR System server is running, the daemon will restart all the appropriate threads and continue to run as it normally should. You can adjust the configuration time that the daemon monitors the AR System server by modifying the following line in the Daemon.properties file: com.remedy.arsys. daemon.monitor=<num> Where <num> is any valid integer and this parameter is measured in minutes. If you set <num> to 5, the daemon waits five minutes before checking to see if the server is running. Note: The name of the server is not used in this line. If you do not want to wait, restart the daemon as soon as the AR System server starts. Making changes to mailbox configuration If you make changes to the configuration of any mailbox or remove the mailbox by deleting the entry for this mailbox, you do not need to restart the engine. The daemon will notice the change, but not immediately. The daemon usually checks for configuration changes every 30 minutes (the default setting). If you want to shorten this time, add or modify the following line in the Daemon.properties file: com.remedy.arsys. daemon.<ar_system_server_name>.interval=<num> Where <num> represents an integer value and the parameter is measured in minutes. Fixing common problems with the engine 259

260 BMC Remedy Action Request System 7.0 Note: By shortening the time, the daemon will make more frequent calls to the AR System server. If you are not making many changes to the configuration, you should wait the default 30 minutes, or manually restart the entire engine system after making the configuration changes. The same process applies when you make changes to an existing user, if you change the Internet address on the form. The daemon notices this change based on the predefined interval. Submitting requests across different time zones A user who submits an request or query using a date/time field from a machine that is located in a different time zone than the machine where the engine is installed, might experience the following problems: The query result might not be the same as a BMC Remedy User query result. The query result might not be correct. A request might be registered with an unexpected date or time. These problems occur because the time zone is not adjusted between the BMC Remedy Engine and the client machine. To avoid these problems, users should submit requests and queries to an engine machine located in the same time zone. For more information, see Displaying date/time or numeric values in notifications on page 104. Verifying permissions for the Windows accounts If the BMC Remedy Engine will not run as a Windows service, verify that it can be run manually using the following procedure. Note: If you are using MAPI, log in to the server as the Windows account used to start the engine service. 260 Chapter 7 Troubleshooting

261 To verify permissions for Windows accounts 1 Open a command prompt. Administering BMC Remedy Engine 2 Change directories to the AR System installation directory. 3 At the prompt, run start.bat. 4 If the mail process does not run, verify that the engine user account has the advanced user rights and necessary permissions as described in the Installing guide. 5 If you are not using MAPI, verify that the engine user account has the appropriate file system permissions on the AR System directory. Note: If you are using an MS Exchange server with SMTP and either POP3 or IMAP4, verify that your Exchange server has the SMTP gateway enabled as well as either POP3 or IMAP4 functionality. Troubleshooting request processing and notify filters The engine can experience problems if submissions are not formatted correctly. If an incorrect address is specified on an outgoing notification, or an out-of-office reply is received, items that are not valid submissions will reside in the AR System mail server mailbox. To avoid such problems, create a rule in your program that checks the body of the message for text you require users to include in submissions, such as query or submit. If the message does not contain this text, set the rule to forward the to the AR System administrator and delete it. This rule performs these functions: It prevents problems with the BMC Remedy Engine due to improper request formatting. It prevents undeliverable messages from firing duplicate notify filters. If a message triggers a notify filter and is returned as undeliverable, it is returned to the mail queue, where it causes the filter to fire again. It alerts the administrator to the types of messages being submitted incorrectly, so the administrator can instruct users as to the correct procedures for formatting and submitting messages. Fixing common problems with the engine 261

262 BMC Remedy Action Request System Chapter 7 Troubleshooting

263 A Examples Appendix of templates The examples in this appendix demonstrate how you can use templates to execute a specific set of instructions on an AR System form. You can copy and paste these examples into the body of an message, or you can use the examples to create your own templates. For more information, see Chapter 6, Using templates. The following topics are provided: Creating templates to search for Request ID (page 264) Creating templates to search for fields (page 265) Creating templates to perform searches using qualifications (page 266) Creating templates that include attachments (page 267) Creating an content template with Submit and Query actions (page 268) Creating an reply using result templates in HTML format (page 270) status template in HTML format (page 273) Adding a header template and a footer template (page 275) Examples of templates 263

264 BMC Remedy Action Request System 7.0 Creating templates to search for Request ID You must use the Query Action label (or its alias) to perform a search action. The following examples use templates that have been exported using BMC Remedy Administrator and show how to modify them. You can, however, create the template using a text editor. To create an template to search for a request ID 1 Export the template for the form that you want to make available for searching. The following is an example of an exported mail template. # File exported Tue May 21 21:38: Schema: vacation Server: polycarp Login: Password: Action: Submit Values: Submit, Query Format: Short Values: Short, Full Submitter!2!: Short-Description!8!: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b In the fields section of the template, define only the Request ID. It must have a field ID value of 1. c Enter the Request ID of the entry to be retrieved. d Remove all other fields from the mail template. (The only field in the body should be!1! <RequestID_number>.) The following example shows an exported template that was modified to search for a request ID: Schema: vacation Server: polycarp Login: Password: Action: Query Format: Short Values: Short, Full!1!:TT Appendix A Examples of templates

265 Creating templates to search for fields To create an template to search for a field Administering BMC Remedy Engine 1 Export the template for the form that you want to make available for searching. An example of a mail template for a form follows. # File exported Tue May 21 21:38: Schema: AR-HD Calls Server: polycarp Login: Password: Action: Submit #Values Submit, Query Format: Short #Values Short, Full Source! !: Phone #Values: Phone, AR System, , NMP, ACD Caller Impact! !: Low Values: High, Medium, Low Last Name! !: Phone Number! !: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b Set the Format option if you want a format other than the default (Short). c Edit the fields portion of the template to include the fields you are searching, but remove all other information. The following example shows an exported template that was modified to search for multiple fields. Schema: AR-HD Calls Server: polycarp Login: Password: Action: Query Format: Full Source! !: Phone Caller Impact! !: Low Creating templates to search for fields 265

266 BMC Remedy Action Request System 7.0 Creating templates to perform searches using qualifications To create an template to search using a qualification 1 Export the template for the form that you want to make available for searching. The following example shows a mail template for a form: # File exported Tue May 21 21:38: Schema: AR-HD Calls Server: polycarp Login: Password: Action: Submit Values: Submit, Query Format: Short Values: Short, Full Source! !: Phone Values: Phone, AR System, Caller Impact! !: Low Values: High, Medium, Low Last Name! !: Phone Number! !: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b Remove all fields in the message and include a Qualification label. The following example shows an exported file that was modified to search using the Qualification label. Schema: AR-HD Calls Server: polycarp Login: Password: Action: Query Format: Short Qualification: 'Source' = "Phone" OR 'Source' = " " 266 Appendix A Examples of templates

267 Administering BMC Remedy Engine Creating templates that include attachments The following is an example of an template that includes an attachment field. To create an template that includes attachments 1 Export the template for the form that you want to make available for submitting. Make sure that the form contains an attachment pool and a valid attachment field. 2 Edit the template to include the label and value for an attachment field (for example, Attach! !:), as shown here: # File exported Fri Mar 07 10:30: Schema: Submit Server: polycarp Login: Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full Submitter! 2!: Short Description! 8!: Attach! !: <====== (Manually add this line based upon the attachment field name and database ID) Note: Make sure that you use the ID of the attachment field, not the attachment pool. 3 In a third-party client tool such as MS Outlook Express, create a new . 4 Copy and paste the template into the body of the 5 Add all the required values, for example, Login name, password, and so on. 6 Supply the attachment file name including the extension after the attachment field parameter. Creating templates that include attachments 267

268 BMC Remedy Action Request System 7.0 The following is an example of a user template filled out with a filter.log file attached. Schema: Submit Server: polycapr Login: Demo Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full Submitter! 2!: Demo Short Description! 8!: Submitting with attachment file. Attach! !: filter.log 7 Insert your filter.log attachment file anywhere in the . If the attachment name including the extension is not supplied in the template, the submission will fail. 8 Send the to the incoming mailbox. Creating an content template with Submit and Query actions The following example submits an entry into a form, then queries that same form. When creating or modifying templates, any values that are defined before the Action label are global and apply to all the actions specified. Any value declared after the Action statement takes precedence over the global definition for that action only. In the following example, the Schema and Server label/value pairs are global, and therefore apply to both the Submit and Query actions. Schema: HD Incident Server: polycarp Login: Demo Password: Action: Submit # Values: Submit, Query Format: Full # Values: Short, Full Submitter! 2!: $USER$ Short Description! 8!: Need to create new post office box.!last Name!: Stampovich!First Name!: Ivan 268 Appendix A Examples of templates

269 Administering BMC Remedy Engine! !: Sunnyvale!Phone!: !Status!: Assigned!Impact!: Medium!Item!: !Category!: Applications!Type!: Office!Problem Summary!: Need to create new post office box.! !: boot.ini Action: Query Qualification: 1=1 If you did not specify a template for the reply, the BMC Remedy Engine would reply with the results shown in Figure A-1: Figure A-1: Reply to action template using default format In addition, the Query action returned the Submit entry to the user, along with any other entries that met the qualification. Because no template was defined as a Results Template, the BMC Remedy Engine used the default internal text format. Creating an content template with Submit and Query actions 269

270 BMC Remedy Action Request System 7.0 Creating an reply using result templates in HTML format For the engine to include a Result Template in the reply , enter the Result Template label/value pair as a global declaration in the body of your , as in the following extract: Schema: HD Incident Server: polycarp Result: HDIN Content Login: Demo Password:... When the BMC Remedy Engine sends the reply , it will use the result template shown in Figure A-2: Figure A-2: Reply to action using a result template For a detailed example, see Using HTML result templates with outgoing on page Appendix A Examples of templates

271 Administering BMC Remedy Engine The Result Template must be stored in the AR System Templates form before it can be used in the . For more information, see Storing templates in the AR System Templates form on page 209. If graphics are included, and these are not contained in the HTML file, the graphics must also be added using the Template Attachments tab of the AR System Templates form. For more information, see Adding attachments to HTML templates on page 211. In this template, variables correspond to a field on the HD Incident form on which the template is based (for example, #$$Last Name$$#). The administrator only specifies the fields that are of interest. For more information, see Variables on page 203. When you send your , the BMC Remedy Engine parses and executes the instructions in the Results template. It formats the reply and substitutes values for the variables. For more information about results templates, see Result Template label on page 197. Sample HTML result template If you create your result templates with HTML, you can professionally format the reply results that users see. Figure A-3: HTML result template Creating an reply using result templates in HTML format 271

272 BMC Remedy Action Request System 7.0 The following HTML code was used to create the result template shown in Figure A-3. Copy, paste, and then adapt what you need for your own result template. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML><HEAD><TITLE>HDIN_Content</TITLE> <META http-equiv=content-type content="text/html; charset=iso "> <META content="mshtml " 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=" ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request ID$$#">#$$Request ID$$#</a> </TD> <TD width="21%"> </TD> <TD width="14%"> </TD> <TD width="37%"> </TD></TR> <TR bordercolor=#cccccc> <TD colspan=5><b><font color=# size=3><u>requester Information </U></FONT></B></TD></TR> <TR bordercolor=#cccccc> <TD width="11%" height=56> <DIV align=center><img height=40 src="people.gif" width=38></div></td> <TD width="17%" height=56><b><font size=3>last Name</FONT></B></TD> <TD width="21%" height=56><font size=3>#$$last Name$$#</FONT></TD> <TD width="14%" height=56><b><font size=3> </font></b></td> <TD width="37%" height=56><font size=3>#$$ Address$$#</FONT></TD></TR> <TR bordercolor=#cccccc> <TD colspan=5><font size=3><b><font color=#008000><u>incident Information </U></FONT></B></FONT></TD></TR> <TR bordercolor=#333333> <TD bordercolor=#cccccc width="11%" rowspan=3> <DIV align=center><font size=3></font><font size=3><b><img height=43 src="tools.gif" width=46></b></font></div></td> <TD bordercolor=#cccccc width="17%"><b><font size=3>impact</font></b></td> 272 Appendix A Examples of templates

273 Administering BMC Remedy Engine <TD bordercolor=#cccccc width="21%"><font size=3>#$$impact$$#</font></td> <TD bordercolor=#cccccc width="14%"><b><font size=3>status</font></b></td> <TD bordercolor=#cccccc width="37%"><font size=3>#$$status$$#</font></td></tr> <TR> <TD width="17%"><b><font size=3>category</font></b></td> <TD width="21%"><font size=3>#$$category$$#</font></td> <TD width="14%"><b><font size=3>type</font></b></td> <TD width="37%"><font size=3>#$$type$$#</font></td></tr> <TR> <TD width="17%"><b><font size=3>item</font></b></td> <TD width="21%"><font size=3>#$$item$$#</font></td> <TD width="14%"><b><font size=3>assigned To</FONT></B></TD> <TD width="37%"><font size=3>#$$assigned To$$#</FONT></TD></TR> <TR> <TD bordercolor=#cccccc colspan=5> <HR> <FONT size=3></font></td></tr></tbody></table></td></tr></tbody></ TABLE><B><FONT color=# size=3></font></b></body></html> status template in HTML format For the engine to include a Status Template in the reply 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 , as in the following extract: Schema: HD Incident Server: polycarp Status Template: Status Default Login: Demo Password:... The Status Template must likewise be stored in the AR System Template form. When you send your , the BMC Remedy Engine parses and executes the instructions in the content template. If there is an error, the resulting status will be formatted like Figure A-4. The engine substitutes values for the variables. status template in HTML format 273

274 BMC Remedy Action Request System 7.0 Figure A-4: Reply with status template For more information about status templates, see Status Template label on page Appendix A Examples of templates

275 Administering BMC Remedy Engine Adding a header template and a footer template For the engine to include a Header Template (or Footer Template) in the reply , enter the Header Template label/value pair as a global declaration in the body of your , as in the following extract: Schema: HD Incident Server: polycarp Result Template: Result Template Header Template: Default Header Footer Template: Default Footer... The resulting including the header template will be formatted like Figure A-5. Figure A-5: Reply with header template You can also add a header or footer template to an by selecting it in the relevant field of the Templates tab of the AR System Messages form. The template fields on the AR System Messages form are used to determine the templates used when creating an outgoing message. The label/ value pair method is used when requesting results from a server by way of . Adding a header template and a footer template 275

276 BMC Remedy Action Request System 7.0 In each case, the templates must be stored in the AR System Templates form before they can be used in the . For more information, see Storing templates in the AR System Templates form on page 209. If graphics are included, and these are not contained in the HTML file, the graphics must also be added using the Template Attachments tab of the AR System Templates form. For more information, see Adding attachments to HTML templates on page 211. For more information, see Header Template and Footer Template labels on page Appendix A Examples of templates

277 B Appendix engine installation worksheets This appendix contains installation worksheets for UNIX and Windows. The worksheets include both basic installation and configuration information. Use a separate worksheet for each engine. The following topics are provided: UNIX Installation and configuration worksheets (page 278) Windows Installation and configuration worksheets (page 282) engine installation worksheets 277

278 BMC Remedy Action Request System 7.0 UNIX Installation and configuration worksheets This section includes worksheets for installing and configuring the engine on UNIX. You might need to obtain some of the configuration information from your server system administrator. UNIX Installation worksheet Print this sheet for each of the engines you are installing. Fill out your values ahead of time and use your values in conjunction with the installation instructions. Required information Installation directory Java installation directory Description Path to the directory where the engine CD-ROM is mounted and where the ed_install file is located. Note: Upgrades or overwrites only: Make sure that the default path is the path to your existing installation. Path to the Java root directory, which contains the /bin and /jre directories. Default path: /usr/java<version>/ <root_directory_location> Your value AR Server name Name of the AR System server that the engine connects to. Note: For multiple AR System servers on the same machine: To maintain the correct dependency relationship between the engine and its dedicated AR System server, enter the AR System server that connects to the engine you are installing. Port number TCP port number for the AR System server that the engine connects to. Do not enter a value if the server you specified uses a portmapper. Note: You must specify a port number if the engine and AR System server are on opposite sides of a firewall. 278 Appendix B engine installation worksheets

279 Administering BMC Remedy Engine Required information Description Your value RPC port number AR System administrator user name AR System administrator password Application Service password RPC port number for the AR System server that the engine connects to. Do not enter a value if the server you specified uses a portmapper. Name of the user that has administrator privileges for the AR System server. This user must have permissions to import and manage forms, and to set values in the ar.conf file. Password for the AR System administrator user. Password associated with some applications, such as Flashboards. To set the password, choose File > Server Information and click the Connection Settings tab. UNIX Configuration worksheet Print this sheet for each of the engines you are installing. Fill out your values before you install according to the type of protocol you are using (for example, MAPI or POP3) and the type of mailbox you are configuring (incoming or outgoing). Use your values in conjunction with the configuration instructions during installation. If you configure your incoming and outgoing mailboxes during installation, your engine will be able to send and receive immediately because the values are stored in the AR System Mailbox Configuration form. You can modify these values after you complete the installation. UNIX Incoming mailbox Use this worksheet to record your values for the incoming mailbox. Incoming mailbox information MBOX Name Description Descriptive incoming mailbox name (for example, ARSystem -Incoming). Your value UNIX Installation and configuration worksheets 279

280 BMC Remedy Action Request System 7.0 Incoming mailbox information Description Your value Server Name Name of the server that the engine connects to. Note: For multiple AR System servers on the same machine: To maintain the correct dependency relationship between the engine and its dedicated AR System server, enter the AR System server that connects to the engine you are installing. Server Type Type of protocol that the server uses. MBOX Incoming Mailbox Path Full path to the incoming mailbox for the user account. For example: /usr/spool/mail/arsystems Check the /etc/aliases file to confirm that the path you enter is the correct path. Or run the following command: /usr/lib/sendmail -bv -v [mailbox_username] Incoming User Home Path POP3 or IMAP4 Mailbox Name Full path of the user account home directory. For example: /usr/arsystem Descriptive incoming mailbox name (for example, ARSystem -Incoming). Server Type Type of protocol that the server uses. POP3 or IMAP4 SSL Server Name/IP Secure Socket Layer option enabled. Name or IP address of your company s server. Note: For multiple AR System servers on the same machine: To maintain the correct dependency relationship between the engine and its dedicated AR System server, enter the AR System server that connects to the engine you are installing. 280 Appendix B engine installation worksheets

281 Administering BMC Remedy Engine Incoming mailbox information Description Your value Server Port Port number for your company s server. Default values: POP3: 110 POP3 with SSL: 995 IMAP4: 143 IMAP4 with SSL: 993 Server User Server Passwords Name of the user or administrator of the account. Obtain this information from your server administrator. Password associated with the server user. UNIX Outgoing mailbox Use this worksheet to record your values for the outgoing mailbox. On UNIX, all outgoing mailboxes are configured using SMTP. Outgoing mailbox information for SMTP Mailbox Name Display Name Address Server Name/IP Server Port Description Descriptive name (for example, ARSystem - Outgoing). Descriptive name that appears in the From: line of outgoing s. address of the account owner. Note: If your display name is ARSystem and your address is [email protected], your From: line would be: From: ARSystem [[email protected]] Name or IP address of your company s server. Port number for your company s server. Default values are: SMTP: 25 SMTP with SSL enabled: 465 Your value UNIX Installation and configuration worksheets 281

282 BMC Remedy Action Request System 7.0 Outgoing mailbox information for SMTP Server User Server Password Description Name of the user or administrator of the account. Password associated with the server user. Your value Windows Installation and configuration worksheets This section includes worksheets for installing and configuring the engine on Windows. You might need to obtain some of the configuration information from your server system administrator. Windows Installation worksheet Print this sheet for each of the engines you are installing. Fill out your values ahead of time and use your values in conjunction with the installation instructions. The information about this worksheet begins after the Welcome and software license agreement screens are displayed during installation. Required information Description Your value Installation directory AR Server Name Port Number RPC Port Number Path to the directory where you plan to install the engine. Name of the AR System server that the engine connects to. Note: For multiple AR System servers on the same machine: To maintain the correct dependency relationship between the engine and its dedicated AR System server, enter the AR System server that connects to the engine you are installing. TCP port number for the AR System server that the engine connects to. Do not enter a value if the server uses a portmapper. RPC port number for the AR System server that the engine connects to. Do not enter a value if the server uses a portmapper. 282 Appendix B engine installation worksheets

283 Administering BMC Remedy Engine Required information Description Your value AR System Administrator User Name AR System Administrator Password Application Service Password Name of the user who has administrator privileges for the AR System server. This user must have permissions to import and manage forms, and to set values in the ar.cfg file. Password of the AR System administrator user. Password associated with some applications, such as Flashboards. To set the password, choose File > Server Information and click the Connection Settings tab. Windows Configuration worksheet Incoming mailbox information MAPI Mailbox Name Print this sheet for each of the engines you are installing. Fill out your values ahead of time according to the type of protocol you are using (for example, MAPI or POP3) and the type of mailbox you are configuring (incoming or outgoing). Use your values in conjunction with the configuration instructions during the installation. If you configure your incoming and outgoing mailboxes during installation, your engine will be able to send and receive immediately. Windows Incoming mailbox Use this worksheet to record your values for the incoming mailbox. Description Descriptive name (for example, ARSystem - Incoming). Your value Server Type MAPI server. MAPI Profile Name of the MS Exchange profile you created in the preinstallation section in Chapter 2, BMC Remedy Engine installation and setup. POP3 or IMAP4 Mailbox Name Descriptive name (for example, ARSystem - Incoming). Windows Installation and configuration worksheets 283

284 BMC Remedy Action Request System 7.0 Incoming mailbox information Server Type SSL Server Name/IP Server Port Server User Server Passwords Description POP3 or IMPAP4 server. Secure Socket Layer option enabled. Name or IP address of your company s server. Port number for your company s server. Name of the user or administrator of the account. Password associated with the server user. Your value Outgoing mailbox information MAPI Mailbox Name Display Name Address Windows Outgoing mailbox Use this worksheet to record your values for the outgoing mailbox. Description Descriptive name (for example, ARSystem - Outgoing). Descriptive name that appears in the From: line of outgoing s. address of the account owner. Note: If your display name is ARSystem and your address is [email protected], your From: line would be: From: ARSystem [[email protected]] Your value Server Type Type of server protocol. MAPI Profile Name of the MS Exchange profile you created in the preinstallation section in Chapter 2, BMC Remedy Engine installation and setup. SMTP Mailbox Name Descriptive name (for example, ARSystem - Outgoing). Display Name Descriptive name that appears in the From: line of outgoing s. 284 Appendix B engine installation worksheets

285 Administering BMC Remedy Engine Outgoing mailbox information Description Your value Address address of the account owner Note: If your display name is ARSystem and your address is your From: line would be: From: ARSystem Server Type Type of server protocol. SMTP SSL Server Name/IP Server Port Server User Server Password Secure Socket Layer option enabled. Name or IP address of your company s server. Port number for your company s server. Port used for connecting to the server where this mailbox is stored. Default values are: SMTP: 25 SMTP with SSL enabled: 465 Name of the user or administrator of the account. Obtain this information from your server administrator. Password associated with the server user. Windows Installation and configuration worksheets 285

286 BMC Remedy Action Request System 7.0 Windows MAPI logon settings If you chose MAPI for incoming mailboxes, use this worksheet to record your logon settings. Logon settings Description Your value Windows NT user Name of the domain user who has access to the Exchange profile mailbox. This user also has domain permissions to start the engine as a service. Password Password corresponding to the Windows user. Windows NT Domain Name of the Windows domain you created in the preinstallation section of Chapter 2, BMC Remedy Engine installation and setup. 286 Appendix B engine installation worksheets

287 C Setting Appendix up UNIX mailboxes You can use the following procedure to establish a mailbox address for the UNIX engine. These are meant only as generic guidelines. If you have questions about implementation, you should consult your UNIX system administrator for details. To set up the AR System mailbox, you must have UNIX superuser (root user) access on the UNIX server. To set up UNIX mailboxes 1 Set up an ARSystem user account in the /etc/passwd file, as in the following example (new entry in bold): root:x:0:1:0000-admin(0000):/:/sbin/sh daemon:x:1:1:0000-admin(0000):/: bin:x:2:2:0000-admin(0000):/usr/bin: sys:x:3:3:0000-admin(0000):/: adm:x:4:4:0000-admin(0000):/var/adm: lp:x:71:8:0000-lp(0000):/usr/spool/lp: smtp:x:0:0:mail daemon user:/: uucp:x:5:5:0000-uucp(0000):/usr/lib/uucp: listen:x:37:4:network Admin:/usr/net/nls: nobody:x:60001:60001:uid no body:/: noaccess:x:60002:60002:uid no access:/: ARSystem:x:50:10:AR System mail user:/home/arsystem:/bin/sh Setting up UNIX mailboxes 287

288 BMC Remedy Action Request System Edit the /etc/aliases file and add the alias ARSystem with the mailbox of /usr/ spool/mail/arsystem, as follows: /etc/aliases file ####################### # Local aliases below # ####################### # Alias for AR System mailbox ARSystem:/usr/spool/mail/ARSystem You can also choose a different name, as needed. Verify this step for your UNIX operating system; it might be different for your platform. In particular, the path to your mail folder might be different from /usr/spool/mail/. Note: On some UNIX platforms, you need to run the newaliases command to have the ARSystem aliases recognized. See your UNIX system administration documentation or UNIX system administrator if you have questions or problems. The directory /usr/spool/mail will vary between UNIX platforms. 3 Create the mailbox file you defined for this user in the /etc/aliases file or / usr/lib/aliases file (HPUX), by performing the following command: # touch /usr/spool/mail/arsystem 4 Change the group name to daemon, or to the owner of the mailbox alias name, as in the following example: # chgrp daemon /usr/spool/mail/arsystem Note: The group name varies between UNIX platforms. For most UNIX platforms, it is the group daemon, while on HPUX, it is mail. To verify the proper group name to use, check the group name for the mail directory by using the command ls -ldg. 5 Change the mailbox permissions so they are readable and writable by all, as in the following example: # chmod 666 /usr/spool/mail/arsystem ls -laf /usr/spool/mail/arsystem -rw-rw-rw-- 1 daemon 0 May 30 16:55 /usr/spool/mail/arsystem 288 Appendix C Setting up UNIX mailboxes

289 D Upgrading Appendix option parameters This appendix contains a table of the AR System configuration parameters used in the pre-5.1 BMC Remedy Mail Server and their equivalents (if available) in the 7.0 engine. Upgrading option parameters 289

290 BMC Remedy Action Request System 7.0 engine update parameters Pre-5.1 options Function 6.0 (or greater) engine equivalent Address (UNIX only) Default-Password Default-Schema Default-Server The address the mail process watches for AR System messages. The AR System password to use if no password is specified in the submitted message. The form to use if no form is specified in the submitted message. The AR System server to use if no server is specified in the submitted message. MBOX: Address is defined by the inbox path (the default mailbox is the mailbox for the user that starts the engine). POP3/IMAP4: Address is defined by the server user name. Must be specified by using a user instruction template. For more information, see Overview Sending incoming with user instructions on page 216. Note: The value that is set in the user instruction template will not be overwritten by the incoming . This is defined in the Default Workflow Form field in the incoming mailbox Advanced Configuration tab. The AR System server that the engine connects to that is defined in the Daemon.properties file. 290 Appendix D Upgrading option parameters

291 Administering BMC Remedy Engine Pre-5.1 options Function 6.0 (or greater) engine equivalent Default-User Include-Original- On- Failure Include-Original- On- Success MailNotifyDir (Windows only) Exchange-Profile (Windows only) Exchang box (Windows only) Poll-Interval The AR System login to use if there is no login specified in the submitted message. A flag indicating whether to include the full text of the original message in a reply to a failed submission. A flag indicating whether to include the full text of the original message in a reply to a successful submission. Valid values are T and F. Indicates the full path name for the mailntfy directory that holds all of the notifications the server sends to the armailex service. The armailex service deletes them after they are processed. The name given to the configuration of your MS Exchange client s operation. The MS Exchange mailbox name referenced in your Exchange client s profile configuration (found in the MS Exchange Server properties, accessible through the Control Panel mail icon). The number of seconds to wait between polls to the mailbox to check for new messages. The minimum interval is 5 seconds. Must be specified by using a user instruction template. For more information, see Overview Sending incoming with user instructions on page 216. Note: The value that is set in the user instruction template will not be overwritten by the incoming . Not used. Not used. Not used. This parameter is set in the AR System Mailbox Configuration form in the Basic Configuration tab for MAPI Server Type only. This parameter is set in the AR System Mailbox Configuration form outgoing mailbox in the Advanced Configuration tab for MAPI Server Type only. This parameter is set in the AR System Mailbox Configuration form in the Basic Configuration tab for each mailbox. engine update parameters 291

292 BMC Remedy Action Request System 7.0 Pre-5.1 options Function 6.0 (or greater) engine equivalent Query-Match-Full Query-Match-Short Reply-Failure Defines the maximum number of matches that can be returned for a successful Full Format search request. For example, if a user submits a search request with Full Format indicated and the search matches 120 items, only the first 25 are returned. Defines the maximum number of matches that can be returned for a successful Short Format search request. For example, if a user submits a search request with Short Format indicated and the search matches 120 items, only the first 50 are returned. The address to use for replies to failed submissions. Use this to redirect replies for failed submissions to a third party rather than the message sender. This field only applies to submissions, not searches. To suppress replying to a failed submission, perform one of the following tasks: For UNIX, set the address to /dev/null (or to an address directed to /dev/null in the mail aliases file with a line such as nobody: /dev/ null). Set Reply-Failure to Discard if /dev/null does not work for your system. For Windows, set the address to Discard. Not used. Not used. Not used. 292 Appendix D Upgrading option parameters

293 Administering BMC Remedy Engine Pre-5.1 options Function 6.0 (or greater) engine equivalent Reply-Success Required-Schema SaveSentItem Required-Server ExchangeNTDomain The address to use for replies to successful submissions. Use this to redirect replies for successful submissions to a third party rather than the message sender. This field only applies to submissions, not searches. To suppress replying to a successful submission, perform one of the following tasks: For UNIX, set the address to /dev/null(or to an address directed to/dev/null in the mail aliases file with a line such as nobody: /dev/null). For Windows, set the address to Discard. The only form for which submissions are accepted. If there is a Schema line in the submitted message, it must contain this form name, or the submission is rejected. If there is no Schema line, the Default- Schema setting in the configuration file must match this form name, or the submission is rejected. A flag indicating whether to save items that AR System sends. Valid values for this option are T and F. The default value is F (do not save sent items). The only server for which message requests can be submitted. Messages are rejected if any other server is specified. Messages that do not specify a server are rejected unless the Default-Server option is defined. If you specify a required server and a default server, you must use the same server for both options. The default value is no required server. Windows only: Used during installation. The name of the domain in which the Exchange account resides. Do not modify this parameter. Not used. If the Force Default Workflow form is set to Yes, then the Default Workflow form will be the required schema. See MAPI Saving outgoing notifications on page 75 and Performance and configuration settings on page 236. This can be enforced by setting the application password or by using a security key. For information, see Upgrades from the BMC Remedy Engine on page 31. engine update parameters 293

294 BMC Remedy Action Request System 7.0 Pre-5.1 options Function 6.0 (or greater) engine equivalent ExchangeNTAccount ExchangeNTPassword -Notify-From LogoffSleep Max-Notify-Mail-Line- Len UseDateCheckOnFrom Environment ARDATE Windows only: Used during installation. The name of the Exchange mail server account. Do not modify this parameter. Windows only: Used during installation. The encrypted password for the Exchange account. Do not modify this parameter. The sender name to use for filter-generated notifications where no subject is specified. Only trusted users may use this name. This field is limited to 29 characters. A flag indicating whether to check the date format when verifying new messages. In general, this option exists for backward compatibility only. Valid values for this option are Y and N. The default value is N (do not check date format). The date and time format used by the program. UNIX only: This value consists of a string of operators as defined by the strftime library call. (Some combinations are displayed successfully but cannot be translated for input.) If you do not set this variable, the system uses the date format for the language specified by the LANG environment variable. Windows only: This value consists of a string of operators as defined by Regional Settings. If you do not set this variable, the system uses the date format specified in the Regional Settings of the user account that runs the service. For information, see Upgrades from the BMC Remedy Engine on page 31. For information, see Upgrades from the BMC Remedy Engine on page 31. This is set by using the display name and address fields on the Advanced Configuration tab in the outgoing mailbox. Not used. Not used. Not used. Not used. 294 Appendix D Upgrading option parameters

295 Administering BMC Remedy Engine Pre-5.1 options Function 6.0 (or greater) engine equivalent ARDATEONLY ARRPC The date format used by the program. UNIX only: This value consists of a string of operators as defined by the strftime library call. (Some combinations are displayed successfully but cannot be translated for input.) If you do not set this variable, the system uses the date format for the language specified by the LANG environment variable. Windows only: This value consists of a string of operators as defined by Regional Settings. If you do not set this variable, the system uses the date format specified in the Regional Settings of the user account that runs the service. UNIX only: The specific RPC socket to communicate with during the run of the program. If no AR System server is running on the identified socket, an error is returned, and the program does not run. Not used. The RPC socket that the engine uses is defined in the Daemon.properties file. If you want to define an RPC socket in a template, see Using label/value pairs in templates on page engine update parameters 295

296 BMC Remedy Action Request System 7.0 Pre-5.1 options Function 6.0 (or greater) engine equivalent ARTIMEONLY MAIL The time format used by the program. UNIX only: This value consists of a string of operators as defined by the strftime library call. (Some combinations are displayed successfully but cannot be translated for input.) If you do not set this variable, the system uses the date format for the language specified by the LANG environment variable. Windows only: This value consists of a string of operators as defined by Regional Settings. If you do not set this variable, the system uses the date format specified in the Regional Settings of the user account that runs the service. UNIX only: The directory where files are stored. The default is /usr/ mail (HP and Solaris) or /var/spool/mail (IBM). Not used. This is set using the inbox path. If the inbox path is not set, then the mail environment variable is used. 296 Appendix D Upgrading option parameters

297 E BMC Appendix Remedy Engine forms The BMC Remedy Engine provides a set of administration, user, and workflow forms for configuring and processing from your mail server. These forms are generated during installation and imported when you restart your AR System server. The following topics are provided: engine administration forms (page 298) engine user forms (page 307) engine workflow forms (page 311) Note: If all of the forms were deleted for any reason, they are imported automatically by default when the AR System server is restarted. To prevent these forms from being imported by default when the AR System server is restarted, go to the ar.conf (ar.cfg) file and set the option - Import-Form-By-Default to F. For more information, see Configuring SSL for the engine on page 76. If some, but not all, of the forms were deleted previously, a message will appear when you restart the AR System server, informing you that you must import those forms manually. BMC Remedy Engine forms 297

298 BMC Remedy Action Request System 7.0 engine administration forms This section describes the following administration forms that are available with the engine: AR System Mailbox Configuration AR System Templates AR System User Instruction Templates AR System Error Logs AR System Security AR System Mailbox Configuration Use the AR System Mailbox Configuration form to create mailboxes and specify their use. For each mailbox, the form provides a name and address for the mailbox administrator, actions associated with the mailbox, connection and security provisions, and defaults. For more information, see Configuring outgoing mailboxes on page 53 and Configuring incoming mailboxes on page 59. Incoming mailbox Basic and Advanced Configuration tabs Field name Mailbox Name Mailbox Function Status Server Type Description Enter the name of the incoming mailbox. Select whether mailbox is Incoming or Outgoing. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled. Select the protocol. Incoming mailboxes include following protocols: POP3 IMAP4 MBOX MAPI 298 Appendix E BMC Remedy Engine forms

299 Administering BMC Remedy Engine Field name Polling Interval (Minutes) Server Requires SSL Inbox Path Server Name/ IP Server Port Server User Server Password Profile Name Associated Mailbox Name Action Use Original Template Format Description Enter the number of minutes after which the engine will check for incoming mail from the mail server for this mailbox. Enables the secure socket layer. Used only with POP3 and IMAP4. Enter the full path file name to the mbox file corresponding to the user account that will be used. Used only with MBOX. Enter the name or IP address of the mail server used in your organization. Used only with POP3 and IMAP4. Enter the port used for connecting to the mail server. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Used only with POP3 and IMAP4. If you do not enter a port number, the following default values will be used: POP3: 110 POP3 with SSL: 995 IMAP4: 143 IMAP4 with SSL: 993 Enter the user name of the administrator or user for this account. Used only with POP3 and IMAP4. Enter the user name of the administrator or user for this account. Used only with POP3 and IMAP4. Enter the name of the MS Exchange profile to be used for incoming mailbox. Used only with MAPI. Enter the name of an outgoing mailbox used to reply to incoming s that require a response. Select Parse to enable the engine to detect and process instructions included in an incoming message, or accept the default value of None for no action. Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (pre-5.1 Remedy Mail Server) and thus ignore special HTML fields and XML formats. engine administration forms 299

300 BMC Remedy Action Request System 7.0 Field name Reply With Result Reply With Entry Enable Modify Actions Default Workflow Form Force Default Workflow Form Use Security Key Use Supplied User Information Use From Address Description Select Yes to enable the results of an Action to be included with an reply, or select No if results should not be included. Select Yes to return the complete entry of a submit or modify action. Select No to use the default single-line entry. Select Yes to enable modify actions, or No to prevent modify actions from being performed. Enter the name of the form upon which the engine will execute instructions found within the incoming message if no specific form is specified in the message. Select Yes if the Default Workflow Form should be used regardless of what was specified in an incoming . This action will confine all instructions received by this mailbox to the specified form. Select Yes to force a security key to be used for incoming mail to this mailbox. Select Yes to use AR System server login information that might be included within the incoming message. Select Yes to use the address of the sender as a form of authentication. Outgoing mailbox Basic and Advanced Configuration tabs Field name Mailbox Name Mailbox Function Status Server Type Description Enter the name of the outgoing mailbox. Select whether mailbox is Incoming or Outgoing. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled. Select the protocol. Outgoing mailboxes include the following protocols: SMTP MAPI 300 Appendix E BMC Remedy Engine forms

301 Administering BMC Remedy Engine Field name Polling Interval (Minutes) Server Requires SSL Server Name/ IP Server Port Server User Server Password Profile Name Associated Mailbox Name Default Outgoing Mailbox Display Name Address Reply To Address Organization Description Enter the number of minutes after which the engine will check for new outgoing mail waiting to be sent from this mailbox. Enables the secure socket layer. Used only with SMTP. Enter the name or IP address of the mail server used in your organization. Used only with SMTP. Enter the port used for connecting to the mail server. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Used only with SMTP. If you do not enter a port number, the following default values will be used: SMTP: 25 SMTP with SSL: 465 Enter the user name of the administrator or user for this account. Used only with SMTP. Enter the user name of the administrator or user for this account. Used only with SMTP. Enter the name of the MS Exchange profile to be used for the outgoing mailbox. Used only with MAPI. Enter the name of the incoming mailbox that will be used to receive instructions or notifications. Select Yes so that all outgoing messages for which an outgoing mailbox is not specified will be sent using information in this entry. Enter the name you want displayed in the From line of the outgoing . Enter the full address of the administrator or owner of this mailbox. Enter the Reply-to address for the mailbox owner or administrator, if you plan to enable users to reply to notification messages sent from this mailbox. For clients that display an organization name, enter the name of the mailbox owner, or administrator s organization. engine administration forms 301

302 BMC Remedy Action Request System 7.0 Field name Delete Outgoing Notification Messages Default Addressing Default To Default CC Default BCC Default Templates Header Template Footer Template Status Template Result Template Description Select Yes to have outgoing notification messages deleted from the AR System Messages form after they have been sent from this mailbox. Enter the addresses to send to if addresses have not been specified in the Messages tab for a notify filter or escalation. Enter the default addresses for those who should receive outgoing messages from this mailbox. Enter the default addresses for those who should receive copies of outgoing messages from this mailbox. Enter the default addresses for those who should receive blind copies of outgoing messages from this mailbox. If a user creates a message without specifying a template in the Templates tab for either Notify filter or escalation actions, then this template will be used by default. Enter the template to be used as the default header template. Enter the template to be used as the default footer template. Enter the template to be used as the default status template. Enter the template to be used as the default result template. AR System Templates form Use the AR System Templates form to create, display, and modify templates applied to messages. You can use this form to create standard templates that users can access for creating specific types of messages. For each template, this form provides: the unique template ID; the format used and a name and description for the template; the language encoding used; and information about attachments associated with this template. If you want graphic elements to appear in your , you can add these as attachments to the template in the AR System Templates form. You must store templates in the AR System Templates form before you can use them. 302 Appendix E BMC Remedy Engine forms

303 Administering BMC Remedy Engine For more information, see Storing templates in the AR System Templates form on page 209. Field name Template Format Encoding Template Name Description File Name Add Attachment button (HTML templates only) Modify Attachment button (HTML templates only) Delete Attachment button (HTML templates only) Description Choose the format of template, either Text or HTML. Choose the language setting used to read and parse the contents of templates. If no setting is specified, the default encoding of the local system is employed. Enter the name of the template. The contents of the Template Name field are automatically populated if you attach a new file, then click inside the field. You can edit the name as needed. After saving your template, the AR System Templates form uses data-driven workflow to populate menus in the engine forms that use templates, for example, when you add an template to a Notify action. (Optional) Select the template files from the Attachment field. Includes size and label information. Click to open the AR System Attachments form in New mode. Lets you select and add an attachment (for example, HTML file or bitmap) that is always used with a specific template. Click to open the AR System Attachments form in Search mode so you can modify an attachment. The template will not be available for use until the engine cache is updated. Click to delete the attachment from AR System Attachments form. engine administration forms 303

304 BMC Remedy Action Request System 7.0 Field name Refresh Table button (HTML templates only) Add Existing menu (HTML templates only) Description Click to refresh the table after you have added, modified, or deleted an attachment. Adds an existing attachment to the template. AR System User Instruction Templates form Use the AR System Templates form to store administrator-defined instructions for specific actions, and to associate those instructions with a template defined in the AR System Templates form. These instructions can include variables whose values are provided when the instructions are executed. For each instruction template, the form provides the template name, name of the mailbox with which the instructions are associated, and the instructions themselves. For more information, see Overview Sending incoming with user instructions on page 216. Field name Instruction Template ID Template Name Mailbox Name Instruction Description System-generated unique ID. The contents of this field are read-only. Menu lets you select template that is executed as the content of user instruction and used in the . Menu lets you associate incoming mailbox used with user instruction. Valid character string consisting of Action label and value used to access user instruction field. 304 Appendix E BMC Remedy Engine forms

305 Administering BMC Remedy Engine AR System Error Logs form Use the AR System Error Logs form to store logs of errors that have occurred during transmissions, as well as all incoming and outgoing mail messages, log connection status information for servers and the AR System server, start and stop times for the engine, and configuration changes. Each log entry includes the ID for the mailbox and the message, the message type, message number, how the error message was generated, and the text of the error message. For more information, see Error and system status logs on page 229. Field name Log Message ID and Create Date Mailbox ID Number Message Type Message Number Generated By Message Text Description Message ID and date on which error was created. Number of the message to which the log applies. Either an error log or a status log and the severity level of the message. Severity levels are as follows: Severe: Errors that prevent successful execution of a specific task and might require administrator intervention. This is the default value. Warning: Errors that can cause problems when executing a task. Info: Status information. Config: Information related to mailbox configuration. For configuration information, see Configuring outgoing mailboxes on page 53 and Configuring incoming mailboxes on page 59. Fine: Internal exceptions, which are handled by the application but logged for tracing purposes. Finer: Trace logs that record specific tasks as they are executed within the application. Error number associated with the message. Error generated either by the engine or by the AR System server. Description of the error. engine administration forms 305

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

307 Administering BMC Remedy Engine engine user forms This section describes the user forms available with the engine: AR System Messages AR System Attachments AR System Attachment Join AR System Messages form Use the AR System Messages form to store information for outgoing and incoming messages. Each message is stored as an entry in the AR System Messages form. For each message, this form provides the name of the mailbox from which the message was generated, the message type, name and organization of the mailbox owner; names of recipients sent to and copied; the text of the message (in HTML, plain text format, or a combination of both); and (under a separate tab) a list of any attachments included with the message. For information about using the Messages form to troubleshoot traffic between incoming and outgoing , see Chapter 4, Outgoing . Field name Mailbox Name Mailbox Type Display Advanced Options Description Name of configured mailbox. Select whether mailbox is Incoming or Outgoing. Select Yes to display the advanced options available for viewing information and errors. Message tab Field name From: Reply To: Organization: Description Name of the mailbox the is sent from. Reply-to address for the mailbox owner or administrator, if you plan to enable users to reply to notification messages sent from this mailbox. For clients that display an organization name, the name of the mailbox owner, or administrator s organization. engine user forms 307

308 BMC Remedy Action Request System 7.0 Field name To: CC: BCC: Subject: Priority: Description addresses for those who should receive outgoing messages from this mailbox. addresses for those who should receive copies of outgoing messages from this mailbox. addresses for those who should receive blind copies of outgoing messages from this mailbox. Subject line for your . Value to use in the message to get the desired MS Outlook priority. Numbers from 1 to 100 are acceptable. Attachments tab Field name Add Attachment Modify Attachment Delete Attachment Refresh Table Add Existing Description Includes attachment with outgoing . Lets you modify attachment or attachment name. Removes attachment from outgoing . Refreshes table after you have added, modified, or deleted an attachment. Includes previously saved attachment with outgoing . Advanced Options tab Templates, Variable Replacements, and Attachment Alternatives tab Field name Header Template Content Template Footer Template Field Values AR System Server AR System Server TCP Port Description Template to be used as the header template. Template to be used as the content template. Template to be used as the footer template. Value for a variable in the template. With qualification variables, name of the server on which the form resides. With qualification variables, any access information necessary. 308 Appendix E BMC Remedy Engine forms

309 Administering BMC Remedy Engine Field name AR System Server RPC Number AR System Form Qualification Attachment Alternatives (attachment pool) Plain Text Content Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding Description With qualification variables, any access information necessary. With qualification variables, name of the AR System form to which these values apply. Query used to retrieve data and substitute it in the . Attachment pool enables you to add the content of your as a plain text, HTML, or RTF attachment, instead of typing it into the Body field in the Message tab. Language encoding used. Language encoding used. Language encoding used. Language encoding used. Message Information tab Field name Message ID and Date Received Execute/Send At Description Message ID and date on which error was created. Number of the message to which the log applies. engine user forms 309

310 BMC Remedy Action Request System 7.0 Field name Parse Message Send Message Description Indicates if incoming message was parsed. Options are: No Yes Error Parsed & Executed Indicates if outgoing message was sent. Options are: No Yes Error Sent Error Sending-Retrying Errors tab Field name Log Message Type (attachment pool) Log Message Text Description Enables users to view error messages if their is not sent correctly. If a request fails to submit, the original message is returned. If a request fails to submit, the error message that indicates the reason for the failure is returned. AR System Attachments form Use the AR System Attachments form to create, display, and modify information about attachments used with s and templates, including incoming . For each attachment, the form provides a unique ID, the type of attachment (for example, a text file), the name of the attachment, whether the attachment is an attachment or a template attachment, the file name, size, and label. 310 Appendix E BMC Remedy Engine forms

311 Administering BMC Remedy Engine Administrators can access this form from the Template form if an attachment is needed for a new template. Users can access attachments from this form when they compose an message. Field name Type Attachment Name File Name (attachment pool) Description or Template attachment. Used for storing attachments for both incoming and outgoing s. It also stores attachments for templates, such as a graphic for an HTML template. Name of attachment. Enables users to view error messages if their was not sent correctly. AR System Attachment Join form The BMC Remedy Engine uses the AR System Attachment Join form for mapping attachments to messages. WARNING: Because this information is used internally by the engine, you should not create or modify entries in this form. engine workflow forms This section describes the workflow forms available with the engine. AR System Instructions AR System Instruction Parameters AR System Association AR System Instructions form The BMC Remedy Engine uses the AR System Instructions form to store instructions obtained when incoming is parsed. WARNING: Because this information is used internally by the engine, you should not create or modify entries in this form. engine workflow forms 311

312 BMC Remedy Action Request System 7.0 AR System Instruction Parameters form The BMC Remedy Engine uses the AR System Instruction Parameters form to store parameters specified for administrator-defined instructions. WARNING: Because the information in this form is used internally by the engine to store instructions, you should not create or modify entries in this form. AR System Association form The BMC Remedy Engine uses the AR System Association form to store associations between an message and one or more attachments, or between a template and one or more attachments. For incoming messages, this information includes the association between the message and any attachments included with the message. For outgoing messages, this information includes associations for attachments that should be included when the message is sent. For each association, the form provides: Unique ID. Source type ( or template). If the source type is template, the form reflects the association between a template and any attachments that should be included when that template is used. An example is an HTML template with graphics that must be included to make sure that the message is displayed correctly. Source ID (the ID of the or template). Destination type ( attachment). Destination ID (the ID of the attachment). This association enables multiple s to be associated with one attachment, or one to be associated with multiple attachments. WARNING: Because this information is used internally by the engine, you should not create or modify entries in this form. 312 Appendix E BMC Remedy Engine forms

313 Index A Action label 194 actions definition 17 modify 195 query 195 examples 264 submit 194 user-defined 196 Add Shortcut, including ARTask attachments 91 adding attachments alternative 124 HTML templates 213 outgoing 116 adding templates to Templates form 210 to outgoing 118 advanced configuration incoming mailbox 61 outgoing mailbox 56 advanced solutions, overview 21 advanced options incoming 178 outgoing 117 advanced search bar, qualification label 197 appearance of , improving 22 application service passwords determining invalid 253 removing invalid 254 startup parameters 235 AR System API errors 231 installing 33 sending an to 143 stopping and starting, troubleshooting 259 AR System Association form 312 Attachment Join form 311 Attachments form description 310 HTML templates 212 outgoing 115 use 310 Error Logs form accessing 230 description 305 using 229 Instruction Parameters form 311, 312 Instructions form 311 Mailbox Configuration form 298, 302 Messages form advanced options 178 browser, displaying in 110 description 307 troubleshooting, used with 226 using 307 variable replacements 108 Security form 306 Templates form for storing templates 209 User Instruction Templates form 304 AR System Engine. See engine Index 313

314 BMC Remedy Action Request System 7.0 architecture of engine 227 ARTask attachments, including in notifications 91 Association form, description 312 association, 311, 312 Attachment Alternatives tab, using 124 Attachment Join form 311 attachments adding alternative 124 description 310 outgoing 116 previously saved 213 to 310 deleting Templates form 214 outgoing 116 exporting templates with, to another server 215 maximum size, setting 239 modifying Templates form 214 outgoing 116 outgoing , including 114 submissions, including with incoming 154 templates 211 Attachments form description 310 HTML templates 212 outgoing 115 use 310 Authentication label 193 B basic format, templates 200 BMC Remedy Administrator invalid passwords, removing 254 templates, exporting mail 188 BMC Remedy Engine. See engine BMC Remedy Mail Server configuration parameters 290 original template format, using 63 upgrading to 6.x engine UNIX 31 Windows 30 C certification authorities (CA) article describing CA procedures 77 configuring 76 check buttons, HTML 202 client 144 modifying entries 154 submitting entries 150 configuration advanced incoming mailbox 61 outgoing mailbox 56 notifications, deleting automatically 104 security 69 Daemon.properties file 237 form entry interval time, changing 76 incoming mailboxes 59 security 69 Mailbox Configuration form 298 modify actions 73 outgoing mailboxes 53 security 71 overview 52 performance 76 Remedy Mail Server configuration parameters, using in engine 290 reply with results 72 retrieval time, changing form entry 76 SSL 76 TCP port 34 testing 65 troubleshooting mailbox 259 UNIX incoming mailbox, during installation 45 installation, during 45 outgoing mailbox, during installation 46 Windows incoming mailbox, during installation 36 installation, during 35 outgoing mailbox, during installation 38 console output used in troubleshooting Index

315 Administering BMC Remedy Engine content templates description 185 HTML outgoing 107 outgoing , HTML 137 XML outgoing 107 creating instruction templates 219 templates additional tips 209 using Remedy Administrator 188 user instructions 218, 220 workflow to modify requests 167 D data-driven workflow, using 97 date formats in templates 206 debugging See also troubleshooting -Dmail.debug=true batch files 242 options in logging.properties file 231 sample debug log MBOX 248 SMTP 247 Windows 243 UNIX engine 245 Windows engine 242 default workflow form 64 digital signatures 76 direct access URLs, using in notifications 89 displaying date, time, or numeric values, in notifications 104 -Dmail.debug=true debug option UNIX 245 Windows 242 domains warning, not using in notifications 90 E account, definition 16 adding saved attachments 116 administration forms 298 client AR System 144 entries, modifying 154 (continued) client (continued) entries, submitting 150 queries, sending 144 deleting an attachment 116 digital signatures 76 forms list AR System Association 312 AR System Attachment Join 311 AR System Attachments 115, 212, 310 AR System Error Logs 305 AR System Instruction Parameters 311, 312 AR System Instructions 311 AR System Mailbox Configuration 298 AR System Messages 108, 120, 307 AR System Security 306 AR System Templates 210 AR System User Instruction Templates 304 improving appearance 22 modifying an attachment 116 notifications, deleting automatically 104 priority in sending 90, 111 querying AR System 144 receiving 14 request processing, troubleshooting 261 sending 14 sending to the AR System 143 special forms 297 templates. See templates user forms 307 workflow forms 311 account, definition 16 engine administering (Webcast) 87 architecture 227 definition 14 association 312 attachments 310 instruction parameters 311, 312 messages 307 errors 231 Index 315

316 BMC Remedy Action Request System 7.0 engine (continued) forms 297 heap size, defining 252 installation UNIX 41 Windows 32 mail server, relation to 18 modify actions, configuring 73 overview 14 Remedy Mail Server configuration parameters 290 sample scenario 18 security 306 starting 47 startup parameters 235 stopping 47 templates 304 terminology 16 threads 227 UNIX starting 48 stopping 48 Windows starting 48 stopping 48 Messages form. See AR System Message form Daemon.properties file configuring 237 invalid passwords, removing 255 performance and configuration 237 updating 235 using 233 Entry ID label 200 environment variables, setting UNIX 31 Windows 27 Error Logs form described 305 overview 229 troubleshooting engine 229 errors AR System API 231 incoming 181 internal engine 231 errors (continued) logs 229 outgoing 125 escalations. See workflow examples, copying and pasting into mail client 145 expiration date, security key 306 exporting templates description 188 outgoing workflow 169 F failures, transmission or instruction 230 fields notifications, defining in 91 order in notifications 92 files Daemon.properties 233 logging.properties 231 filters. See workflow footer templates 198, 275 description 186 HTML 186 label 198 Form label 192 Format label 196 incoming , using with 153 formats, template basic 200 HTML 201 label and values 200 variables 201 XML 201 forms administration forms 298 default workflow 64 entry interval times, changing 76 importing by default 297 sample for modify actions 168 system-generated forms 297 user forms 307 workflow forms 311 forms list AR System Association 311, 312 AR System Attachment Join Index

317 Administering BMC Remedy Engine forms list (continued) AR System Attachments description 310 HTML templates 212 outgoing 115 AR System Error Logs 305 AR System Instruction Parameters 311, 312 AR System Instructions 311 AR System Mailbox Configuration 298, 302 AR System Messages 307 description 307 overview 108 variable replacements 120 AR System Security 306 AR System Templates 210 AR System User Instruction Templates 304 G global fields and variables 205 global parameter declarations in templates 203 glossary 16 H header templates description 186 HTML 186 HTML banners in outgoing 129 label 198 reply template, adding to 275 using 198 heap size, defining for engine 252 HTML check buttons 202 field types, allowable 201 format , using to 147 format of templates 201 header templates 186 input controls 113 menu fields 202 modify instructions, sending 161 notifications, sending from workflow 85 outgoing content templates 107 HTML (continued) outgoing , sending 111 radio buttons 202 references and examples 112 result template sample code 271 result templates 186 status templates 186 templates 201 text fields 202 I ID label 199 IMAP4 definition 15 incoming mailbox, configuring 60 Microsoft Exchange Server and 261 importing forms by default 297 incoming advanced options 178 attachments 154 Format label, with queries 149 Format label, with submits 153 modifying entries 154 overview 143 qualifications, including 148 sample scenario 142 sending queries 144 submitting entries 150 syntax for label/value pairs 144 templates 185 templates, using 177 user instructions, sending 222 user-defined instructions 216 using 143 workflow triggered 144 incoming mailboxes, configuring See also incoming , mailboxes advanced 61 description 59 IMAP4 60 MAPI 60 MBOX 61 POP3 60 security 69 Index 317

318 BMC Remedy Action Request System 7.0 incoming mailboxes, configuring (continued) testing 67 UNIX during installation 45 Windows during installation 36 incoming mailboxes, definition 17 installation See also preinstallation components 26 documentation, reviewing 26 engine UNIX 41 Windows 32 Java, correct version needed 253 MAPI logon settings, entering 39 mailbox, changing login information 49 preparation 27 MBOX preparation 27 preinstallation steps 26 UNIX tasks 31 Windows tasks 27 setup 25 SSL 27 UNIX 41 basic information, entering 42 completing 47 configuration information, entering 45 environment variables, setting 31 Windows 32 basic information, entering 33 completing 40 configuration information, entering 35 environment variables, setting 27 worksheet, using 26 instruction or transmission failures 230 Instruction Parameters form 311, 312 instructions definition 17 modify, sending (HTML) 161 modify, sending (plain text) 157 Instructions form 311 internal engine errors 231 Internet Message Access Protocol. See IMAP4 interval time, changing form entry 76 J Java components required for installation 26 correct version needed for installation 253 JRE directory 32 K Key label 199 key terms describing engine 16 keywords content templates for outgoing s in notifications, using in 99 submissions 153 L label aliases Encryption and Encryption Key 199 Entry ID, EntryID, and RequestID 200 Footer and Footer Template 198 Header and Header Template 198 Query and Search 197 Result and Result Template 197 RPC Number 193 Schema 192 Status and Status Template 198 TCP 193 User, User Name, Name, and Login Name 193 label/value pairs See also templates definition 191 format, templates 200 syntax Action label 194 format 200 same as templates 144 sending 108 labels Action 194 Authentication 193 Footer Template 198 Form 192 Format 196 incoming queries 149 incoming submits Index

319 Administering BMC Remedy Engine labels (continued) Header Template 198 Instruction 194 Key 199 Language 194 Login 193 Modify 157!Name/ID! 199 Password 193 Qualification 197 incoming , using with 148 Query 144 Request ID 200 Result Template 197 RPC 193 Server 192 Status Template 198 Submit incoming 150 TCP Port 193 variables, substituting with 205 Language label 194 local parameter declarations in templates 203 local system accounts for engine service 249 logging AR System Error Logs form 229 debugging 231 errors 229 logging.properties file 231 message information 125, 180 severity levels 305 system status 229 troubleshooting problems 250 Login label 193 M mail server definition 16 engine, relation to 18 troubleshooting 256 Mailbox Configuration form 298 mailboxes changing configuration 65 mailboxes (continued) configuration troubleshooting 259 configuration overview 52 creating 53 definition 16 polling interval 60, 239 See also incoming mailboxes UNIX AR System mailbox, setting up 287 outgoing mailboxes MAPI definition 15 engine login information, changing after installation 49 incoming mailbox, configuring 60 logon settings, entering 39 outgoing mailbox, configuring 54 outgoing notifications, saving 75 preparation steps for installation 27 transport problems UNIX, fixing 258 Windows, fixing 257 upgrading 27 MBOX definition 15 incoming mailbox, configuring 61 preparation steps for installation 30 sample debug log 248 mechanism, used for notifications 90 menu fields, HTML 202 Message Information tab status information for incoming 180 status information for outgoing 125 messages AR System Messages form 307 content, determining 125 notifications, used in 94 overview 85 Messages form description 307 outgoing overview 108 variable replacement 120 Messages tab, notifications 93 Messaging Application Programming. See MAPI MIME (Multipurpose Internet Mail Exchange) 15 Index 319

320 BMC Remedy Action Request System 7.0 modify actions action label 195 additional restrictions 165 constraints 165 engine, configuring 73 enabling 63 entries, using incoming 154 HTML, using 161 instructions, sending (HTML) 161 instructions, sending (plain text) 157 Modify label, incoming 157 plain text, using 157 querying entries 174 replying 160 sample form, creating 168 sample scenario 155 searching entries 174 modify key 195 Multipurpose Internet Mail Exchange. See MIME N Name label 199 non-root installations with UNIX 31 Notes displaying HTML in mail clients 128 Java version, correct version needed for installation 253 notifications, creating with join forms using Submit execute condition 86 Password field, do not modify 195 queries and optimizing performance 126 style sheets linked to HTML not supported 211 notes restricted use of keywords in content templates 99 notifications ARTask attachments, including 91 deleting automatically 104 direct access URLs 89 displaying date, time, or numeric values 104 field order 92 fields, defining 91 filter workflow, creating 168 groups, not using 90 notifications (continued) HTML, using 85 keywords, using in content templates for outgoing 99 mechanism 90 Messages tab, using 93 messages, defining 94 permissions 92, 96 processing 14 replying 171 saving (MAPI) 75 subject lines 91 submit execute condition with join forms 86 templates definition 96 order used 99 tab, using 93 text 89, 169 user name 89 variable, using 205 O outgoing advanced options 117 attachment alternatives 124 errors 125 messages 125 templates 117 variable replacements 119 AR System Messages form 108 attachments, including 114 dynamically assigning templates 99 field value, replacing 120 HTML, sending in 111 message content, determining 125 plain text, sending in 109 professional appearance 126 result templates, using 131 sample scenario 82 syntax for label/value pairs 108 template types 185 templates, creating 105 troubleshooting 226 using header templates as banners 129 using HTML content templates Index

321 Administering BMC Remedy Engine outgoing (continued) using status templates 138 XML templates 135 outgoing mailboxes, configuring See also mailboxes advanced 56 description 53 MAPI 54 security 71 SMTP 55 testing 65 UNIX during installation 46 Windows during installation 38 outgoing mailboxes, definition 17 overviews advanced solutions 21 configuration 52 engine 14 incoming 143 modify instructions with incoming 155 templates 184 workflow to modify requests, using 166 P parameters instruction 311, 312 startup 235 templates 203 Password label 193 passwords application service, specifying 235 identifying invalid 253 removing invalid 254 performance Daemon.properties 237 queries, optimizing 126 retrieval time, changing form entry 76 permissions notifications 92, 96 verifying for Windows account 260 plain text modify instructions, sending 157 outgoing , sending 109 polling interval minutes, configuring 60 seconds, configuring 239 POP3 definition 15 incoming mailbox, configuring 60 Microsoft Exchange Server and 261 Post Office Protocol. See POP3 postinstallation UNIX, stopping and starting engine 48 Windows, stopping and starting engine 48 preinstallation See also installation MAPI and MBOX 27 MAPI preparation steps 27 MBOX preparation steps 30 non-root user issues 31 Remedy mail server upgrade UNIX 31 Windows 30 upgrading UNIX from engine 5.1 or priority of s sent 90, 111 processing notifications 14 professional looking 126 protocols IMAP4 15, 261 MAPI 15 MBOX 15 POP3 15, 261 SMTP 15, 261 Q Qualification label 197 qualifications incoming , including 148 label/value pairs syntax 148 short hand syntax 149 templates, adding to 175 testing 148 query action description 195 incoming 144 label 144 Index 321

322 BMC Remedy Action Request System 7.0 query action (continued) modifying entry 174 performance 126 using 264 R radio buttons in HTML format 202 receiving 14 replying configuring engine 72 modify actions, not changing 161 modify instructions 160 notifications 171 Request ID label 200 requests, submitting across time zones 260 restrictions when modifying entries 165 result templates description 186 HTML 186 label 197 outgoing , using with 131 sample HTML 271 RPC Number label 193 S sample scenarios engine 18 incoming 142 modify actions 155 outgoing 82 user instructions 216 search. See query Secure Sockets Layer. See SSL security See also SSL article describing certification authority 77 certification authorities (CA) 76 configuring keys 70 modify actions 73, 168 security key expiration date 306 Security form 306 sending engine, using 14 incoming , using 143 Server label 192 servers stopping and starting AR System 259 wrong server specified 255 services local system account with engine 249 troubleshooting 260 shorthand qualifications 149 Simple Mail Transfer Protocol. See SMTP Sm@rtCert client 33 SMTP configuring during installation 46 definition 15 gateway 261 outgoing mailbox 55 sample debug log 247 SSL See also security certification authorities (CA), configuring 76 configuring 76 installation 27 starting and stopping engine server, stopping and starting 259 startup parameters 235 troubleshooting 253 UNIX 47 Windows 47 status information reserved variables 208 templates 208 status messages incoming 180 outgoing 125 status templates description 186 example 273 formatting 152 HTML 186 label 198 outgoing , HTML 138 subject lines in notifications Index

323 Administering BMC Remedy Engine submit actions action label 194 notifications with join forms 86 Submit label, incoming 150 submitting requests across time zones 260 submitting in filter workflow 170 entries, using incoming 150 keywords 153 syntax formats of label/value pairs 200 incoming label/value pairs 144 outgoing label/value pairs 108 qualifications 148 shorthand qualification syntax 149 template label/value pairs 194 system status logs 229 system-generated forms 297 T TCP port configuring 34 label 193 templates See also label/value pairs adding 210 AR System Templates form 209 attachments 211 modifying 214 Content 119 creating 185, 188, 209 data-driven workflow, using to set 97 date formats 206 definition 184 deleting attachments 214 dynamic assignment for outgoing 99 examples exporting 188 exporting with attachments to another server 215 fields with, searching 265 Footer 198, 275 formats basic 200 HTML 201 templates (continued) formats (continued) labels and values 200 variables 201 XML 201 Header 198, 275 incoming 177, 185 instruction 216 creating 219 labels and values 191 formats 200 misleading use of term 184 modifying 209 notifications, used in 96 order used in notifications 99 outgoing 185 using 105 outgoing , used with 119 overview 184 parameters 203 qualifications, adding to 175 requests with, searching 266 reserved variables 207 Result 197 Status 198 example 273 storing 209, 302 user instructions 219 syntax for label/value pairs 194 testing 219 tips 209 types of 185 User-Defined Instruction 187, 216 using after an upgrade 215 variables 203 formats 201 Templates form 210 Templates tab notifications 93 using 117 terminology 16 text fields HTML 202 notifications 89, 169 Index 323

324 BMC Remedy Action Request System 7.0 threads, used in engine 227 time zones, submitting requests across 260 tips copying and pasting examples into mail client 145 data-driven workflow, using 97 engine, administering (Webcast) 87 Errors Log form, accessing 230 Messages form in browser, displaying 110 Daemon.properties file, using 234 HTML, using to format 147 incoming can trigger workflow 144 multi-line syntax in variables 200 qualifications to template, adding 175 security keys with modify actions 73, 168 status templates, using to format 152 templates, testing 219 templates, use of term slightly misleading 184 testing qualifications 148 XML file, validating 135 transmission or instruction failures 230 troubleshooting See also debugging advanced options for incoming 178 API errors 231 configuration, testing 65 console output 250 debugging engine 242 -Dmail.debug=true debug mode 242 Messages, using 226 request processing 261 Daemon.properties file performance and configuration settings 236 using 233 error logs 229 failures, transmission or instruction 230 fixing common problems 248 internal errors 231 invalid application service passwords determining 253 removing 254 troubleshooting (continued) logging problems 250 logging.properties file, using for debugging 231 mail server 256 mailbox configuration, making changes to 259 MAPI transport problems UNIX, fixing 258 Windows, fixing 257 notify filters 261 outgoing 226 permissions for Windows accounts, verifying 260 sample debug log 243 starting engine 253 startup parameters 235 submitting requests across time zones 260 system status logs 229 time zones, submitting requests across 260 transmission or instruction failures 230 wrong server specified 255 trusted users 294 U UNIX AR System mailbox, setting up 287 configuration during installation 45 debugging engine 245 installation 41 basic information, entering 42 completing 47 incoming mailbox, configuring during 45 non-root 31 outgoing mailbox, configuring during 46 MAPI transport problems, fixing 258 notifications from server 86 preinstallation tasks 31 starting engine 48 stopping engine 48 upgrading from engine 5.1 or upgrading engine 5.1 or 5.1.1, from 31 MAPI issues Index

325 Administering BMC Remedy Engine upgrading (continued) old templates, using 215 original template format, using from Remedy Mail Server 63 URLs, direct access in notifications 89 User Instruction Templates form 304 user instructions creating 220 incoming , sending 222 results 222 sample scenario 216 variables, using 224 user name field, in notifications 89 User-Defined Instruction templates actions, user-defined 187 definition 187 overview 216 sample scenario 216 user-defined actions 196 users modify actions, using security keys 73, 168 trusted 294 V values definition 191 field, replacing in outgoing 120 format, templates 200 variables 203 Variable Replacement tab AR System Messages form 119 using 119 variables field values and qualifications, using with 205 formats 201 multi-line syntax 200 notifications, using in 205 reserved 207 templates with incoming 177 templates, used in 203 user instructions, using with 224 W warnings domain names, not using 90 group notifications, not using 90 internal information should not be modified 311, 312 modify actions, not changing during reply 161 multiple AR System servers 34, 43 Windows accounts, verifying permissions 260 AR System, installing 33 debugging engine 242 installation basic information, entering 33 completing 40 configuration during 35 description 32 incoming mailbox, configuring during 36 outgoing mailbox, configuring during 38 MAPI transport problems, fixing 257 notifications from server 86 preinstallation tasks 27 services, troubleshooting 260 software, loading for installation 32 starting engine 48 stopping engine 48 workflow data-driven templates, dynamically assigning 99 templates, setting 97 default form 64 dynamically assigning templates to outgoing 99 messages in notifications, using 94 modify requests, creating to 167 notifications, defining in 86 notify action in filter 168 overview, using to modify requests 166 templates in notifications, using 96 triggered by incoming 144 troubleshooting 261 UNIX servers 86 Windows servers 86 worksheet, preinstallation 26 Index 325

326 BMC Remedy Action Request System 7.0 X XML file, validating 135 format of templates 201 outgoing content templates 107 templates 201 templates, using with outgoing Index

327

328 *58475* *58475* *58475* *58475* *58475*