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