BMC Impact Integration Web Services Server Installation and Configuration Guide
Supporting BMC Impact Integration Web Services Server v.7.3.01 June 2009
www.bmc.com
Contacting BMC Software You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada Address
BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA
Telephone
713 918 8800 or 800 841 2031
Fax
(01) 713 918 8000
Fax
713 918 8000
Outside United States and Canada Telephone
(01) 713 918 8800
© Copyright 2003–2007, 2009 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. IT Infrastructure Library® is a registered trademark of the Office of Government Commerce and is used here by BMC Software, Inc., under license from and with the permission of OGC. ITIL® is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office, and is used here by BMC Software, Inc., under license from and with the permission of OGC. Linux is the registered trademark of Linus Torvalds. Oracle is a registered trademark of Oracle Corporation. Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and other countries. TIBCO and ActiveMatrix are trademarks or registered trademarks of TIBCO Software, Inc., in the U.S. and other countries. UNIX is the registered trademark of The Open Group in the US and other countries. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.
Restricted rights legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer support You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”
Support website You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can ■ ■ ■ ■ ■ ■ ■ ■
read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation download products and maintenance report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
Support by telephone or e-mail In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to
[email protected]. (In the subject line, enter SupID:, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC Have the following information available so that Customer Support can begin working on your issue immediately: ■
product information — — —
■
product name product version (release number) license number and password (trial or permanent)
operating system and environment information — — — — —
machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
■
sequence of events leading to the issue
■
commands and options that you used
■
messages received (and the time and date that you received them) — — —
product error messages messages from the operating system, such as file system full messages from related software
3
License key and password information If you have questions about your license key or password, contact BMC as follows: ■
(USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail message to
[email protected].
■
(Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an e-mail message to
[email protected].
■
(Asia-Pacific) Contact your BMC sales representative or your local BMC office.
4
BMC Impact Integration Web Services Server Installation and Configuration Guide
Contents Chapter 1
Introduction
11
Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . New BMC Impact Integration Web Services Server platform . . . . . . . . . . . . . . . . Version 7.3.01 changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC Impact Integration C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a send request is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the receive feature works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12 12 13 14 14 14 15 15 15 16 16 17 18
Chapter 2
19
Installation
Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Atrium Core prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible web services toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to install BMC II Web Services Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining the prerequisite BMC Atrium Core 7.5.00 patch 2. . . . . . . . . . . . . . . . . Installing the BMC II Web Services server (Windows or UNIX) . . . . . . . . . . . . . . BMC II Web Services Server Installation directory contents . . . . . . . . . . . . . . . . . Location of TIBCO documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verifying the status of the related web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before sending events to BMC Impact Manager cells . . . . . . . . . . . . . . . . . . . . . . . How to uninstall BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20 20 21 21 21 22 22 22 22 24 25 25 26 26 30 31
Chapter 3
33
Configuration
Configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO ActiveMatrix Administrator console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iiws_node CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents
34 34 34 37 5
Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Synchronizing BMC II Web Services Server and BMC IM cell connections . . . . . 38 mcell.dir configurations for different server implementations . . . . . . . . . . . . . . . . 40 Adding WSCELL entries to BMC Impact Manager mcell.dir files . . . . . . . . . . . . . 42 Adding BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Troubleshooting tip: BMC II Web Services Server fails to reconnect. . . . . . . . . . . 45 Defining Propagate rules or propagation event policies for BMC IM cells. . . . . . 45 Starting TIBCO-related web services processes (UNIX) . . . . . . . . . . . . . . . . . . . . . 51 Starting TIBCO-related web services processes (Windows) . . . . . . . . . . . . . . . . . . 52 Optional configuration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Configuring high availability cells for the BMC II Web Services Server . . . . . . . . 53 Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Guidelines for configuring attributes of the BMC II Web Services Server . . . . . . 57 Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Modifying log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Setting substitution variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Advanced task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Installing multiple instances of the BMC II Web Services Server on different host systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Chapter 4
BMC Impact Integration Web Services Server administration
67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 How the BMC II Web Services Server reads selector files and parameters . . . . . . . . . 69 Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 mcell.dir file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Index
6
BMC Impact Integration Web Services Server Installation and Configuration Guide
103
Figures Components of the BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . 12 Welcome screen of the BMC Impact Integration Web Services 7.3.01 Installer . . . . . 23 TIBCO ActiveMatrix Administration console: Service Assemblies . . . . . . . . . . . . . . . 27 TIBCO ActiveMatrix Administrator console: iiws_node . . . . . . . . . . . . . . . . . . . . . . . 28 TIBCO ActiveMatrix Administrator console: node containers . . . . . . . . . . . . . . . . . . 29 TIBCO ActiveMatrix Administrator console: Shared resources: HTTP_Server . . . . 29 TIBCO ActiveMatrix console: HTTP_Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 BMC II Web Services Server uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 TIBCO ActiveMatrix Administrator console: Service Assemblies . . . . . . . . . . . . . . . . 35 TIBCO ActiveMatrix Administrator console: Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Event propagation: many instances to one server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Event propagation: many instances to many servers . . . . . . . . . . . . . . . . . . . . . . . . . . 47 HA implementation scenario: primary cell server and web server on same system 54 HA implementation scenario: primary cell server and web server on different systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 HA implementation scenario for BPM and BMC II Web Services Server . . . . . . . . . 57 TIBCO ActiveMatrix Administrator: port number example . . . . . . . . . . . . . . . . . . . . 59 TIBCO ActiveMatrix Administrator: HTTP server example . . . . . . . . . . . . . . . . . . . . 60 TIBCO ActiveMatrix Administrator console: logging configurations . . . . . . . . . . . . 63 TIBCO ActiveMatrix Administrator console: objects to log . . . . . . . . . . . . . . . . . . . . . 64 Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Sample trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Figures
7
8
BMC Impact Integration Web Services Server Installation and Configuration Guide
Tables Components that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location of mcell.dir Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir configurations for queries and for sending events . . . . . . . . . . . . . . . . . . . . mcell.dir configurations for receiving events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables
17 20 21 21 24 38 39 40 41 53 74 75 77 80 83 84 87
9
10
BMC Impact Integration Web Services Server Installation and Configuration Guide
Chapter
1
1
Introduction This chapter presents the following topics: Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . New BMC Impact Integration Web Services Server platform . . . . . . . . . . . . . . . . Version 7.3.01 changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC Impact Integration C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a send request is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the receive feature works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1
Introduction
12 12 13 14 14 14 15 15 15 16 16 17 18
11
Overview to BMC Impact Integration Web Services Server
Overview to BMC Impact Integration Web Services Server The web service client communicates with the BMC Impact Manager instance (cell) by connecting to the BMC II Web Services Server and accessing BMC II Web Services. Figure 1 depicts the components of the BMC II Web Services Server and their interaction with a third-party client. Figure 1
Components of the BMC Impact Integration Web Services Server WSDL File Service interface file Binding Port type Message Type
Web Services Toolkit Third-party client (Service Requestor)
Encrypted Communications
Service Provider
SOAP Messages Synchronous or Asynchronous
Impact Integration Web Service APIs
C APIs
BMC Impact Manager cell or cells
Web Services Server (TIBCO Foundation)
You install the BMC II Web Services Server in a standalone installation on top of BMC Atrium Core v. 7.5.00 patch 2. (You must download and install BMC Atrium Core v. 7.5.00 patch 2 first.) The BMC II Web Services Server can pass events from event providers, such as BMC Performance Manager, to a BMC Event Manager cell or third-party application.
New BMC Impact Integration Web Services Server platform Version 7.3.01 of the BMC II Web Services Server is built and deployed with the TIBCO® ActiveMatrix™ application. The Systinet® server platform is not supported in this or in later versions of the BMC II Web Services Server.
12
BMC Impact Integration Web Services Server Installation and Configuration Guide
Version 7.3.01 changes
Version 7.3.01 changes In version 7.3.01 the following BMC II Web Services Server operations have been deprecated: ■ ■ ■ ■
bmciiws_connect bmciiws_getEvents bmciiws_getQueryResult bmciiws_retrieveQueryResults
If your web services client uses these operations, you must replace them with the corresponding operations listed below: ■ ■ ■ ■
bmciiws_connect_NO_INOUT bmciiws_getEvents_NO_INOUT bmciiws_getQueryResult_NO_INOUT bmciiws_retrieveQueryResults_NO_INOUT
You will need to recompile your client code if you remove the deprecated operations and replace them with the new ones. The mcell subfolder previously found under the installDirectory path has been replaced by the conf subfolder. The BMC Impact Integration Web Services Server does not have a dependency on the BMC Impact Administration Server. You install and run it separately from BMC Impact Administration Server. This TIBCO-based implementation uses the default port number 9080 (instead of 6070) for the HTTP server. The server endpoint address is now http://hostName:portNumber/impactmanager. You now access the published BMC II Web Services Server WSDL at this address: http://hostName:portNumber/impactmanager?wsdl. The previous server configuration file servercfg.xml has been removed. Its functionality is replaced by new configuration parameters that are added to the iiws.conf file. You can define web service related attributes and perform actions such as stopping and starting the BMC II Web Services Server process through the TIBCO ActiveMatrix Administrator console interface. You can access the TIBCO ActiveMatrix Administrator console interface through this default address: http://hostName:8120/amxadministrator/admin.jsp.
Chapter 1
Introduction
13
BMC Impact Integration C APIs
In addition to using the TIBCO ActiveMatrix Administrator console interface, you can also use a new command line interface on either UNIX or Windows to stop, start, or restart the BMC II Web Services Server. The new CLI is iiws_node (start | stop |restart). You execute the iiws_node command from the installDirectory\webServices\bin path. You can execute this CLI command after performing any manual change to configuration files, such as mcell.dir, iiws.conf, iiws.trace, or selector files.
BMC Impact Integration C APIs The BMC II Web Services Server contains the runtime libraries of the BMC Impact Integration C APIs.
WSDL file and SOAP messages The BMC II Web Services Server exposes its APIs through its ImpactManager.wsdl file. It uses the document/literal style of SOAP messaging format to communicate with client programs.
NOTE The BMC II Web Services Server uses encrypted communications. User authentication is not available.
Toolkits and client-side interfaces If you are creating a web service client, BMC recommends that you choose from among the compatible toolkits (see “Compatible web services toolkits for building clients” on page 21). Use the toolkit that supports your programming language (C# , Java, C++, and so forth) to process the ImpactManager.wsdl and generate the client-side stubs. These stubs contain classes and interfaces that are used by the client code. The stubs define how the methods or functions are called. When a client request is initiated, the toolkit serializes the call into a SOAP message and sends it to the server. The server deserializes the SOAP message into a format that the underlying TIBCO Foundation libraries can understand and processes it accordingly.
14
BMC Impact Integration Web Services Server Installation and Configuration Guide
Features of the BMC II Web Services Server
Features of the BMC II Web Services Server This section describes the BMC II Web Services Server’s unique requirement for the mcell.dir file, and it summarizes the different ways in which the BMC II Web Services Server handles client interfaces.
mcell.dir After you install the BMC II Web Services Server, an mcell.dir file is generated with two default entries. In addition to the local cell entry, which most BMC Impact Manager users are familiar with, it also includes an entry for the event listener component called WSCELL. The following example shows the entries with the default port numbers. cell cell
local WSCELL
mc mc
localhost:1828 127.0.0.1:19999
In the standalone BMC II Web Services Server installation, the mcell.dir file is installed under the drive:\installDirectory\webServices\conf directory.
WSCELL event listener An essential component of the BMC II Web Services Server, the WSCELL is an event listener that accepts connections and messages from BMC Impact Manager instances. It is enabled when the BMC II Web Services Server starts. The WSCELL receives events and messages from BMC Impact Manager instances and stores them in a buffer. The BMC II Web Services Server receives the BMC Impact Manager events through the WSCELL event listener. The WSCELL defaults to the local host system (IP address of 127.0.0.1) of the BMC II Web Services Server and listens for events on port number 19999. For each BMC IM cell that sends events to the BMC II Web Services Server, you specify the WSCELL entry that identifies the server in each sending cell’s mcell.dir file. (See “Synchronizing BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.)
Chapter 1
Introduction
15
How a send request is processed
How a send request is processed The BMC II Web Services Server receives the client requests through default port 9080 or a specified port number. It processes the requests and calls the appropriate C API to pass the message to the specified BMC Impact Manager instance.
How a query is processed Using the available query features, you can enable a client to ■ ■
retrieve events, data objects, or both from a specific BMC IM instance return component information about service model component instances that have been published to a specific cell or to multiple cells The service model component queries retrieve dynamic data that is stored in the cell’s memory and in files under the installSolutionsHome\Impact\Server\log\cellName directory. The service model queries can search for and return service model information that has been published to one or more cells.
NOTE These service model queries retrieve component data that has already been published to the cell; they do not query the BMC® Atrium Configuration Management Database.
■
retrieve service model class definitions from a specific BMC IM instance The class definition query retrieves static class definition information stored in the BAROC files under the IMPACT_SOLUTIONS_HOME\Impact\Server\etc\cellName\kb\classes directory.
After the client specifies the initial query and connects with a BMC Impact Manager instance, the BMC II Web Services Server responds with a result handle ID. The client returns the result handle ID with each query request in the query cycle. After receiving the result handle ID, the client sends a request to the server seeking the total number of events or data objects available to the query. The BMC II Web Services Server responds with the total count. To complete the query, the client next requests a specified number of events or data objects, and the server responds with the specified number or at least the available number. The server response is the query result. To end the query cycle and disconnect from the BMC Impact Manager instance, the client sends a bmciiws_endQuery request.
16
BMC Impact Integration Web Services Server Installation and Configuration Guide
How the receive feature works
When querying, the client does not need to invoke a specific connection or disconnection request. With each query request, the client establishes a connection with a specific BMC Impact Manager instance. With the bmciiws_endQuery request, the client disconnects from the BMC Impact Manager instance. If you build an exclusive query client, you do not need to invoke subscription or polling calls. Also, you do not need to build Propagate rules or define propagation event policies to push events from BMC Impact Manager instances to the WSCELL event listener residing on the BMC II Web Services Server.
How the receive feature works You can build a client interface that receives events through polling calls. Table 1 on page 17 describes the essential components for a client interface that receives events. Table 1
Components that support a receive interface
Component
Description
WSCELL
The WSCELL is an event listener that the BMC II Web Services Server starts. Its function is to accept connections from BMC Impact Manager instances at default port number 19999.
Propagate rules or propagation event policies
To receive events from BMC Impact Manager instances, you must define Propagate rules or propagation event policies in the cell for the event types to be sent. The BMC Impact Manager instance sends events to the WSCELL event listener based on the rules or polices that you have defined.
Subscription requests
To receive events, your client interface must invoke subscription requests through the bmciiws_subscribe_reliable() operation. The parameters that the subscription requests pass depend on the polling interface you choose for the client. You can elect to use reliable subscription (reliable is set to True) to guarantee event delivery.
Polling client You can choose to design a polling client that uses a reliable subscription request to maintain a persistent connection with the BMC II Web Services Server and the BMC II C API libraries. When it receives a reliable subscription request from a client, the BMC II Web Services Server persists the events that it receives in response to the client’s subscription request in the %IIWS_ROOT%\cache (or $IIWS_ROOT/cache) directory.
Chapter 1
Introduction
17
Intended audience
NOTE IIWS_ROOT is one of the TIBCO substitution variables. Its default value is installDirectory\webservices.
If your client uses non-reliable subscription, then the BMC II Web Services Server stores events in the installDirectory\webservices\log subdirectory under the name of the service.
Intended audience The intended audience of the BMC II Web Services Server product component is end users and administrators. End users do a minimal amount of configuration to get the BMC II Web Services Server running and use the server to send events. Administrators include systems or applications administrators who are responsible for managing the BMC Impact Manager environment. These administrators should be knowledgeable about BMC Impact Manager administrative tasks, especially the tasks of maintaining the configuration, trace, selector, and the mcell.dir files. The administrator should also be familiar with defining filter criteria that specify the events that pass to and from BMC Impact Manager. To configure and maintain the BMC II Web Services Server, the administrator should be knowledgeable about the TIBCO ActiveMatrix Administrator console interface and TIBCO ActiveMatrix functionality. The administrator should also have a general knowledge of web services. Although web service developers are not part of the intended audience of this guide, they can access the BMC Developer Network at the following URL: http://communities.bmc.com/communities/community/bmcdn There you can find downloads and documentation related to building a web service client through the BMC Impact Integration Developer’s Kit.
18
BMC Impact Integration Web Services Server Installation and Configuration Guide
Chapter
2
2
Installation This chapter presents the following topics: Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible web services toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to install BMC II Web Services Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II Web Services Server Installation directory contents . . . . . . . . . . . . . . . . . Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verifying the status of the related web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before sending events to BMC Impact Manager cells . . . . . . . . . . . . . . . . . . . . . . . How to uninstall BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 2
Installation
20 20 21 21 22 22 24 25 26 26 30 31
19
Installation package contents
Installation package contents The BMC II Web Services Server package consists of the following components: ■ ■ ■ ■
■
server library files server assembly files configuration, selector, mapping, and mcell.dir files Web Services Description Language (WSDL) files and schema definition (XSD) files runtime library files of the BMC II C APIs
Supported operating systems and other resources Table 2 lists the operating systems that are compatible with the TIBCO platform: Table 2
Supported operating systems
Operating system
Version or Service pack
Windows 2003 Server, 32-bit
All
Windows XP, 32-bit
All
Red Hat Enterprise Linux Advanced Server (Intel, 32-bit) 4.0 AS/ES Update 2 SUSE Linux Enterprise Server (Intel, 32-bit)
10.0
Sun Solaris SPARC
10
NOTE The BMC Impact Integration Web Services Server v. 7.3.01 supports a modified subset of the operating systems and versions that BMC Impact Solutions v. 7.3.01 supports.
20
BMC Impact Integration Web Services Server Installation and Configuration Guide
BMC IM support matrix
BMC IM support matrix Table 3 on page 21 lists the versions and features of BMC Impact Manager (BMC IM) that the BMC II Impact Integration Web Services Server supports. Language support for Simplified Chinese, Traditional Chinese, Korean, and Japanese languages is provided. Table 3
BMC IM support matrix
BMC IM version
Event and data exchange
Service model queries
Language support
7.3.00
Yes
Yes
Yes
7.3.01
Yes
Yes
Yes
Atrium Core prerequisite BMC II Web Services Server requires that you install BMC Atrium Core v. 7.5.00 patch 2 before installing BMC II Web Services Server.
Compatible web services toolkits for building clients The BMC II Web Services Server package has been tested against and found compatible with building clients from the following web services toolkits: Table 4
Compatible toolkits for building clients
Vendor
Toolkit
Microsoft
Visual C# .NET 2003
Apache
Axis 1_3, Axis 1_4
Composite
Composite Information Server v. 4.5.00
Chapter 2
Installation
21
Disk space requirements
Disk space requirements UNIX
Windows
TIBCO Stack/Atrium Core
3045 MB
3045 MB
BMC II Web Services Server
50 MB
50 MB
How to install BMC II Web Services Server The installation procedure is a two-tiered process. First, you install BMC Atrium Core 7.5.00 patch 2 from the specified BMC Software download site. Then you install the BMC II Web Services Server from the 7.3.01 BMC Impact Solutions installation CD.
Obtaining the prerequisite BMC Atrium Core 7.5.00 patch 2 Download the BMC Atrium Core 7.5.00 patch 2 from the following BMC Software support site: http://support.bmc.com/arsys/apps/remcspenu.bmc.com/Patch/CS%3APatch/w eb/?cacheid=76981cd6
NOTE You are required to be registered with BMC Software before you can access the download site. If you do not already have a user account (registered email address and password), you must complete and submit the registration form.
Along with the patch, download the accompanying technical bulletin BMC Atrium Core Version 7.5.00 Patch 2. Follow the installation instructions in the technical bulletin. The bulletin tells you how to choose between installing the BMC Atrium Core Web Services or the Web Services Infrastructure (TIBCO stack) option.
Installing the BMC II Web Services server (Windows or UNIX) After successfully installing the Web Services Infrastructure or the BMC Atrium Core Web Services, you then install the BMC Web Services Server. This section describes the procedure for installing the BMC II Web Services Server from the install DVD on the Windows or UNIX platform.
22
BMC Impact Integration Web Services Server Installation and Configuration Guide
Installing the BMC II Web Services server (Windows or UNIX)
Before you begin For UNIX installations, use the same user account for installing both the Atrium Core and BMC II Web Services Server.
To install the BMC II Web Services Server 1 Place or mount the installation DVD in the appropriate device. 2 Navigate to the Impact_Web_Services folder, and open the appropriate platformspecific subfolder.
3 On UNIX, launch the setup_IIWS.sh script file. On Windows, launch the setup_IIWS.exe executable. The Welcome screen is displayed. Figure 2
Welcome screen of the BMC Impact Integration Web Services 7.3.01 Installer
4 Click Next to access the license agreement. 5 Accept the license agreement, and click Next. Chapter 2
Installation
23
BMC II Web Services Server Installation directory contents
6 Specify the installation directory path, or accept the default path. The installation directory variable is IIWS_INSTALL_TOP. Then click Next.
7 Specify the HTTP port number for the BMC II Web Services Server, or accept the default port number 9080.
8 Click Next to view the Installation preview window. You can click Previous to return to an earlier window.
9 Click Install to launch the installation. You should see a window saying that the installation is successful.
10 Click Done.
BMC II Web Services Server Installation directory contents Table 5 on page 24 describes the directory contents of the BMC II Web Services Server installation package. These subfolders are located under the installDirectory folder and the installDirectory\webServices subfolder. Table 5
Directory contents (part 1 of 2)
Directory
Description
deployment
contains build and data file information and templates, both in XML format, together with a zipped service assembly archive file
cache
defined under the substitution variable IIWS_ROOT and created during runtime Maintains a record on the BMC II Web Services Server of persisted events that were requested by the client through the bmciiws_subscribe_reliable() operation. The cache director is empty until the client sends a reliable subscription request. The size of the cache directory is controlled by the RecvBufferSize parameter defined in the iiws.conf file.
conf
contains the default configuration, selector, and trace files that define the communication parameters between the C APIs and the BMC Impact Manager instances. It also contains the mcell.dir file, which identifies the ■ ■
24
BMC Impact Manager instances that the BMC II Web Services component communicates with name of the event listener (WSCELL) that connects with and receives events from BMC Impact Manager instances
BMC Impact Integration Web Services Server Installation and Configuration Guide
Location of TIBCO documentation
Table 5
Directory contents (part 2 of 2)
Directory
Description
log
created at runtime. Contains the persist.dat, RecvBufferFile.dat, and uniqueID.dat files for the server. The RecvBufferFile.dat file stores events on the BMC II Web Services Server that are received from a specified cell provided a propagation rule has been defined. The persist.dat file acts as a persistent buffer for outgoing events and the uniqueId.dat file acts as a counter for the events.
tmp
created at runtime. Contains a log file for the server
locale
contains the language support message catalog files and the iiws.load file. Do not modify these files.
UninstallBMCIIWS
uninstall directory containing the uninstaller executable and related files
Location of TIBCO documentation You or your TIBCO administrator can access and review TIBCO platform documentation under the directory path TIBCO_HOME\amx\2.1\doc.
If you chose the Atrium Core Web Services installation option of BMC Atrium Core 7.5.00 patch 002, then your TIBCO_HOME variable may point to the Atrium_CoreHome\wsc\tibco path—that is, Atrium_CoreHome\wsc\tibco\amx\2.1\doc.
Post-installation To troubleshoot installation errors, you can view the installation log at ■
(Windows) Document and Settings\iidk\Local Settings\Temp\iiws_install_log.txt
■
(UNIX) $TMPDIR/iiws_install_log.txt or $IATMPDIR/iiws_install_log.txt
Chapter 2
Installation
25
Connecting to BMC II Web Services
Connecting to BMC II Web Services After you start the BMC II Web Services Server, you can connect to BMC II Web Services at the service endpoint, as defined by the URL http://hostName:portNumber/impactmanager where hostName identifies where the web services server instance is installed, portNumber identifies the HTTP port (the default is 9080), and impactmanager is the name defined for this web service. To access the BMC II Web Services Server WSDL, connect through this URL: http://hostName:portNumber/impactmanager?wsdl.
Verifying the status of the related web services After installing the BMC II Web Services Server, ensure that the related services are running. Enter the following URL in your browser’s address bar to ensure that you can connect to the WSDL file. http://hostName:portNumber/impactmanager?wsdl
NOTE The string “http://hostName:portNumber/impactmanager” is case sensitive.
You or your TIBCO administrator can verify the other processes by accessing the TIBCO ActiveMatrix Administrator console. Connect to the TIBCO ActiveMatrix Administrator console through this URL address: http://hostName:8120/amxadministrator/admin.jsp. In the TIBCO ActiveMatrix Administrator console, verify the status of ■ ■ ■ ■
■
26
ImpactManagerService service assembly iiws_node node all the containers of the iiws_node Node except for CPP 1.1.0 005 the association of the iiws_node Node with the appropriate HTTP_server and that the HTTP_server is in “running” status the port number associated with the HTTP_server
BMC Impact Integration Web Services Server Installation and Configuration Guide
Verifying the status of the related web services
You can use the GUI command buttons to perform the required actions, such as starting a service assembly, a node, or an HTTP_server.
ImpactManagerService service assembly Choose Deploy to an Environment from the Perspective drop-down list to access the service assembly, an example of which is shown in Figure 3. Figure 3
TIBCO ActiveMatrix Administration console: Service Assemblies
Ensure that the ImpactManagerService service assembly has the status “Running.”
iiws_node Node Choose Configure an Environment from the Perspective drop-down list to access the iiws_node, which is shown in Figure 4 on page 28.
Chapter 2
Installation
27
Verifying the status of the related web services
Figure 4
TIBCO ActiveMatrix Administrator console: iiws_node
Ensure that the iiws_node has the status “Running.”
NOTE The iiws_node is not dependent on the atrium_node. The atrium_node can be stopped without impacting the iiws_node.
Containers of the iiws_node Node From the Configure an Environment perspective, access the containers of the iiws_node by choosing Containers from the list of options. A list of active and unactive containers is displayed, as shown in Figure 5 on page 29.
28
BMC Impact Integration Web Services Server Installation and Configuration Guide
Verifying the status of the related web services
Figure 5
TIBCO ActiveMatrix Administrator console: node containers
Ensure that all containers are activated except for CPP 1.1.0 005.
HTTP_Server of the iiws_node node To check the status of the HTTP_server associated with the node, choose Shared Resources from the list of options in the Configure an Environment perspective. Figure 6
TIBCO ActiveMatrix Administrator console: Shared resources: HTTP_Server
You should see that the specified HTTP_Server is associated with the iiws_node and that its status is “Installed.”
HTTP_Server port number To verify the HTTP_Server port number, choose Configure Enterprise Assets from the Perspective drop-down menu, and select Shared Resources Definitions option at the top row of the panel. The Edit pane is displayed for the HTTP_Server_IIWS entry, as shown in Figure 7 on page 30.
Chapter 2
Installation
29
Before sending events to BMC Impact Manager cells
Figure 7
TIBCO ActiveMatrix console: HTTP_Server
Verify that the ■
port number you specified at installation is associated with the HTTP_server
■
port number you specified for the web service client–for example, BMC Performance Manager–is the same as the number you specified here for the HTTP_server
Before sending events to BMC Impact Manager cells You must configure the installDirectory\webServices\conf\mcell.dir file of the BMC II Web Services Server before it can start sending events to a specified BMC IM cell. See “Synchronizing BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.
30
BMC Impact Integration Web Services Server Installation and Configuration Guide
How to uninstall BMC II Web Services Server
How to uninstall BMC II Web Services Server You can uninstall BMC II Web Services Server by launching the uninstall executable or script file.
To uninstall BMC II Web Services Server 1 Navigate to the installDirectory\UninstallBMCIIWS directory. 2 On UNIX, launch the uninstall.sh script file. On Windows, launch the uninstall.exe executable. The Welcome screen for BMC II Web Services Server uninstallation is displayed. Figure 8
BMC II Web Services Server uninstallation
3 Follow the on-screen instructions and prompts. 4 Click Uninstall to launch the uninstallation process. You can review the uninstallation log at ■
(Windows) Document and Settings\iidk\Local Settings\Temp\iiws_uninstall_log.txt
■
(UNIX) $TMPDIR/iiws_uninstall_log.txt or $IATMPDIR/iiws_uninstall_log.txt
Chapter 2
Installation
31
How to uninstall BMC II Web Services Server
32
BMC Impact Integration Web Services Server Installation and Configuration Guide
Chapter
3
3
Configuration This chapter describes both the required and optional configuration tasks that you perform to enable your BMC II Web Services Server to launch queries and to send and receive events. It describes both the manual configuration tasks that you perform in the BMC Impact Manager files and some of the basic tasks and operations that you perform through the TIBCO ActiveMatrix Administrator console. Configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 34 TIBCO ActiveMatrix Administrator console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 iiws_node CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Synchronizing BMC II Web Services Server and BMC IM cell connections. . . . . 38 mcell.dir configurations for different server implementations . . . . . . . . . . . . . . . 40 Adding WSCELL entries to BMC Impact Manager mcell.dir files . . . . . . . . . . . . 42 Adding BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 45 Defining Propagate rules or propagation event policies for BMC IM cells . . . . . 45 Starting TIBCO-related web services processes (UNIX) . . . . . . . . . . . . . . . . . . . . . 51 Starting TIBCO-related web services processes (Windows) . . . . . . . . . . . . . . . . . . 52 Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Configuring high availability cells for the BMC II Web Services Server . . . . . . . 53 Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Guidelines for configuring attributes of the BMC II Web Services Server . . . . . . 57 Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Modifying log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Setting substitution variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Advanced task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Installing multiple instances of the BMC II Web Services Server on different host systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 3 Configuration
33
Configuration overview
Configuration overview Configuring the BMC II Web Services Server consists of these main processes: ■
Editing configuration files, primarily the mcell.dir, under the MCELL_HOME\etc or installDirectory\webServices\conf directory You can go to these quick-start links for knowledgeable BMC Impact Manager and BMC II Web Services Server users: ■
To enter BMC Impact Manager instances that you want to connect to in the BMC II Web Services Server’s mcell.dir file under \installDirectory\webServices\conf, see “Synchronizing BMC II Web Services Server and BMC IM cell connections” on page 38 and “mcell.dir configurations for different server implementations” on page 40 for more information.
■
To enter the BMC II Web Services Server’s WSCELL information to the mcell.dir file under the MCELL_HOME\etc directory path of each BMC Impact Manager cell from which you want to receive events, see “Adding WSCELL entries to BMC Impact Manager mcell.dir files” on page 42 for more information.
■
Defining propagation rules for the BMC Impact Manager cell’s KB or defining corresponding propagation policies through BMC Impact Explorer
■
Managing TIBCO-based web services processes and attributes through the TIBCO ActiveMatrix Administrator console
Starting and stopping the BMC II Web Services Server This section describes how to start and stop the BMC II Web Services Server process through the TIBCO ActiveMatrix Administrator console and through the iiws_node CLI.
TIBCO ActiveMatrix Administrator console You or your TIBCO administrator can connect to the TIBCO ActiveMatrix Administrator console through this URL address: http://hostName:8120/amxadministrator/admin.jsp.
34
BMC Impact Integration Web Services Server Installation and Configuration Guide
TIBCO ActiveMatrix Administrator console
You need to be concerned with two processes when stopping, starting, or restarting the BMC II Web Services Server: ■
ImpactManagerService service assembly The process name for the ImpactManagerService service assembly is tibcoamxcppcontainer.
You can access the service assembly through the Deploy to an Environment perspective, which is shown on Figure 9 on page 35. Figure 9
TIBCO ActiveMatrix Administrator console: Service Assemblies
■
iiws_node node The process name of the iiws.node is atrium_env_iiws_node.
You can access the node through the Configure an Environment perspective, which is shown in Figure 10 on page 36.
Chapter 3 Configuration
35
TIBCO ActiveMatrix Administrator console
Figure 10
TIBCO ActiveMatrix Administrator console: Nodes
You can use the GUI command buttons in the console to stop and start the service assembly and the node. Different configuration tasks require that you stop, start, or restart the service assembly or the node. You should distinguish when to use each one.
When to stop, start, or restart the ImpactManagerService service assembly Restart the ImpactManagerService service assembly after you have modified any of the following BMC II Web Services Server configuration files that are external to the TIBCO ActiveMatrix Administrator console: ■ ■ ■ ■
36
mcell.dir iiws.conf iiws.trace selector files
BMC Impact Integration Web Services Server Installation and Configuration Guide
iiws_node CLI
While working with attributes in the TIBCO ActiveMatrix Administrator console, restart the ImpactManagerService service assembly after modifying the following attributes, among others: ■ ■ ■
substitution variables logging configurations services
When to start, stop, or restart the iiws_node node While working with attributes in the TIBCO ActiveMatrix Administrator console, you restart the iiws_node node after modifying the following attributes, among others: ■ ■ ■ ■
port numbers HTTP server logging configurations substitution variables
TIP When working in the console, as a general rule, restart the ImpactManagerService service assembly if you modify attributes at the assembly level, and restart the iiws_node if you modify attributes at the node level.
iiws_node CLI As an alternative to using the TIBCO ActiveMatrix Administrator console, you can use the CLI iiws_node (start | stop |restart) to stop and start the BMC II Web Services Server process. You execute the iiws_node command from the installDirectory\webServices\bin path on either a Windows or a UNIX system. You can execute the iiws_node command to initialize changes after manually editing any of the following files: ■ ■ ■ ■
mcell.dir iiws.conf iiws.trace selector files
For example, to restart the BMC II Web Services Server after modifying its mcell.dir file, you would enter this command: installDirectory\webServices\bin iiws_node restart
Chapter 3 Configuration
37
Required configuration tasks
The iiws_node CLI does not apply to any TIBCO-based actions that you would perform exclusively through the TIBCO ActiveMatrix Administrator console.
Required configuration tasks Configuring the BMC II Web Services Server consists of the following required tasks that you perform by manually editing BMC Impact Manager configuration files: Table 6
Required configuration tasks
Task
Description
Page
Synchronizing BMC II Web Services Server and BMC IM cell connections
38 To send events to or query against specific BMC Impact Manager instances, you must enter their cell data in the mcell.dir of the BMC II Web Services Server. To receive events from BMC IM cells, you must enter data about the WSCELL event listener in the mcell.dir file of each BMC Impact Manager instance that sends events to the server.
Defining Propagate rules or propagation event policies for BMC IM cells
To receive events (aside from state change events) from BMC IM cells, 45 you must define Propagate rules or propagation event policies that specify the WSCELL entry of the BMC II Web Services Server.
In addition, whenever you reboot your system, you are required to manually start some of the TIBCO-related web service processes on UNIX and Windows platforms. See the following topics for more information: ■ ■
Starting TIBCO-related web services processes (UNIX) page 51 Starting TIBCO-related web services processes (Windows) page 52
Synchronizing BMC II Web Services Server and BMC IM cell connections Both your BMC Impact Integration Web Services Server installation and its connected BMC Impact Manager instances reference their distinct versions of the mcell.dir files. In the BMC Impact Integration Web Services Server installation, the mcell.dir file has two types of cell entries: ■ ■
38
one for its WSCELL event listener the other for any BMC IM cells with which it communicates
BMC Impact Integration Web Services Server Installation and Configuration Guide
Synchronizing BMC II Web Services Server and BMC IM cell connections
In the BMC Impact Manager instance, its mcell.dir file must specify ■ ■
other cells that it connects with the WSCELL event listener entry of the BMC II Web Services Server to which it sends or propagates events
NOTE You only need to add the WSCELL entry to the mcell.dir of the cell if it is propagating events to the BMC II Web Services Server.
Table 7 on page 39 shows the default directory location of the mcell.dir file in the BMC Impact Manager and in BMC Impact Integration Web Services Server installations. Table 7
Location of mcell.dir Files BMC Impact Integration Web Services Server instance
Operating System
BMC Impact Manager instance
Windows
MCELL_HOME\etc
drive:\installDirectory\ webServices\conf
Solaris, Linux
MCELL_HOME/etc
installDirectory/webServices/conf
mcell.dir entries for multiple cells that comprise a service model To ensure consistent communication among multiple cells containing components of a service model, BMC recommends that you make all cell entries uniform. That is, if a service model is published across cells A, B, C, and D, then the mcell.dir file of each cell should reference all cells in the model. For example, the mcell.dir file of cell A would contain the following entries: cell cell cell cell
cellA cellB cellC cellD
MC MC MC MC
myIMComputer:1828 myIMComputer1:1828 myIMComputer2:1828 myIMComputer3:1828
Similarly, each subsequent cell’s mcell.dir would also reference the other cells in the service model.
Chapter 3 Configuration
39
mcell.dir configurations for different server implementations
mcell.dir configurations for different server implementations You configure the mcell.dir files of the BMC II Web Services Server and its connected BMC IM cells differently depending on the purpose of the BMC II Web Services Server instance: ■ ■ ■
to query events, data, or a service model to send events to receive events
Queries and sending events Table 8 on page 40 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that queries events, data, and the service model or that sends events. The mcell.dir entries are identical for queries and for sending events. Table 8
mcell.dir configurations for queries and for sending events
Purpose of BMC II Web Services Server instance To query events, data, or a service model To send events
mcell.dir entries: BMC II Web Services Server instance mcell.dir entries: BMC IM instances ■ ■
its local WSCELL entry the cell or cells that it communicates with, including all cells that comprise a service model
■ ■
the local cell entry all cells that it communicates with, including all cells that comprise a service model
Figure 11 on page 40 depicts an example mcell.dir configuration of a BMC II Web Services Server that is used to query a service model which is distributed across three BMC IM cells and to send events. The mcell.dir file contains entries for all the cells that comprise the service model. Figure 11 cell cell cell cell
mcell.dir example: BMC II Web Services Server WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC
myWSComputer:19999 myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828
Figure 12 on page 41 shows an example mcell.dir configuration of a cell that comprises part of the service model. The other cells in the service model are also included. The WSCELL entry denoting the BMC II Web Services Server is omitted because in this example the BMC II Web Services Server is not receiving events from the cell.
40
BMC Impact Integration Web Services Server Installation and Configuration Guide
mcell.dir configurations for different server implementations
Figure 12 cell cell cell
mcell.dir example: BMC IM cell cellConnect MC cellConnect 1 MC cellConnect 2 MC
myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828
Receiving events Table 9 on page 41 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that receives events. Whenever a BMC IM cell sends events to a BMC II Web Services Server instance, its mcell.dir must contain the WSCELL entry that points to the server that receives the events. Table 9
mcell.dir configurations for receiving events
Purpose of BMC II Web Services Server instance To receive events from connected cells
mcell.dir entries: BMC II Web Services Server instance ■ ■
its local WSCELL entry the cell or cells that it communicates with, including all cells that comprise the service model
mcell.dir entries: BMC IM instances ■
■ ■
the WSCELL entry identifying the BMC II Web Services Server instance to which it is sending events the local cell entry all cells that it communicates with, including all cells that comprise the service model
Figure 13 on page 42 continues with the example shown in Figure 11 on page 40, in which the mcell.dir of the BMC II Web Services Server contains the three cells that comprise the service model to which the server is connected. You can follow this example to list cells that the server ■ ■ ■
queries sends events to receives events from
NOTE A Propagate rule or a propagation event policy must be defined for each cell from which the server receives events. See “Defining Propagate rules or propagation event policies for BMC IM cells” on page 45 for more information.
Chapter 3 Configuration
41
Adding WSCELL entries to BMC Impact Manager mcell.dir files
Figure 13 cell cell cell cell
mcell.dir example: BMC II Web Services Server WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC
myWSComputer:19999 myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828
Figure 14 on page 42 shows an example mcell.dir configuration of a cell that comprises part of the service model and which sends events to the BMC II Web Services Server. You must include the WSCELL entry to specify the server that receives the events. Figure 14 cell cell cell cell
mcell.dir example: BMC IM cell WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC
myWSComputer:19999 myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828
If your BMC II Web Services Server implementation serves multiple purposes, one of which is receiving events, then follow the mcell.dir examples for receiving events.
Adding WSCELL entries to BMC Impact Manager mcell.dir files This procedure tells you how to add the WSCELL entry, representing the BMC II Web Services Server, to the mcell.dir file of a BMC Impact Manager instance.
Before you begin To verify whether the default port numbers are available, you can run the netstat -a -n command.
To add WSCELL entries to BMC IM mcell.dir files Follow these steps if the cells are propagating events to the BMC II Web Services Server.
1 In a text editor, open the mcell.dir file of the BMC Impact Manager cell that is sending the events to the server. The file is located under the drive:\MCELL_HOME\etc directory.
42
BMC Impact Integration Web Services Server Installation and Configuration Guide
Adding WSCELL entries to BMC Impact Manager mcell.dir files
2 If the BMC IM cell is sending events to a single BMC II Web Services Server, add the WSCELL entry as shown in the following figure. Include the host name or IP address and the port number. The lookup combination of event listener name/host name/port number must be unique for each WSCELL instance. cell cell
cellConnect MC WSCELL MC
myIMComputer:1828 myWSComputer:19999
3 If the cell is sending events to multiple BMC II Web Services Server instances, then add the corresponding WSCELL entries. Specify a unique combination of name, IP address (or host name), and port number for each WSCELL entry. For example, if the server instances are on different systems, you can make the WSCELL entries as shown in the following figure: cell cell cell cell
cellConnect MC WSCELL MC WSCELL1 MC WSCELL2 MC
myIMComputer:1828 myWSComputer:19999 secondWSComputer:19999 thirdWSComputer:19999
Because each BMC II Web Services Server instance is on a different host system, you do not have to specify a distinct port number for each WSCELL event listener. If the server instances are on the same system, your WSCELL entries might be written as in the following figure: cell cell cell cell
cellConnect MC WSCELL MC WSCELL1 MC WSCELL2 MC
myIMComputer:1828 myWSComputer:19999 myWSComputer:20000 myWSComputer:20001
Because the server instances reside on the same system, the WSCELL entries must have a unique port number. See “To Change the Port Number of the WSCELL event listener” on page 60 for the procedure.
4 Save and close the file. 5 Restart the BMC Impact Manager cell. 6 Repeat Steps 1 through 5 in the mcell.dir file of each BMC Impact Manager instance that is sending events to the server.
Chapter 3 Configuration
43
Adding BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file
7 To enable the BMC II Web Services Server to receive events from the connected cell, you must add a Propagate rule that specifies its WSCELL to the Knowledge Base (KB) of the BMC Impact Manager instance. See “Defining Propagate rules or propagation event policies for BMC IM cells” on page 45. Alternatively, you can add a Propagate policy through the BMC Impact Explorer GUI.
Adding BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file For each BMC IM cell with which your BMC IM Web Services Server communicates, you must make a corresponding entry in the server’s mcell.dir file.
To add BMC Impact Manager instance entries to the BMC II Web Services Server’s mcell.dir file 1 In a text editor, open the mcell.dir file located under drive:\installDirectory\webServices\conf or installDirectory/webServices/conf.
2 Add the cell data for each BMC Impact Manager cell that you intend to connect to, as in the following example: cell cell cell cell cell
WSCELL MC cellConnect MC cellConnect1 MC cellConnect2 MC cellConnect3 MC
127.0.0.1:19999 myIMComputer:1828 myIMComputer1:1828 myIMComputer2:1828 myIMComputer3:1828
Guidelines ■
■
Do not change the local host IP address of 127.0.0.1 of the WSCELL entry in the mcell.dir file of the BMC II Web Services Server. If you intend to query or communicate with a service model, include all cells that comprise the service model in the mcell.dir file.
3 Save and close the file. 4 From the TIBCO ActiveMatrix Administrator console, restart the ImpactManagerService service assembly from the Deploy to an Environment perspective.
44
BMC Impact Integration Web Services Server Installation and Configuration Guide
Troubleshooting tip: BMC II Web Services Server fails to reconnect
Alternatively, execute the iiws_node restart CLI from the directory path installDirectory\webServices\bin, as in the following example: installDirectory\webServices\bin iiws_node restart
Troubleshooting tip: BMC II Web Services Server fails to reconnect When you stop and restart the BMC II Web Services Server on UNIX platforms, the WSCELL event listener may fail to reconnect immediately through the listener port that is defined in the BMC II Web Services Server’s mcell.dir file. You will receive an error message similar to the following: Error: IIAPI: BMC-IDK012156E: Unable to setup server, 12:Service endpoint could not be bound. The cause of this error is that the UNIX operating system does not immediately release the port number after you stop the BMC II Web Services Server daemon. To resolve this problem, you can either ■
wait a few minutes before you restart the BMC II Web Services Server; or
■
change the listener port number defined in the server’s mcell. dir file to some other available port If you change the WSCELL port number entry in the server’s mcell.dir file, remember also to change it in the mcell.dir files of all cells that send events to the server.
Defining Propagate rules or propagation event policies for BMC IM cells To enable the BMC II Web Services Server to receive events from a BMC IM cell and pass the events on to a subscribing client, you must do one of the following: ■
add one or more Propagate rules to the KB of the BMC Impact Manager instance that is sending the events
■
define a propagation event policy in the BMC Impact Explorer that specifies the event criteria
The Propagate rule or propagation event policy specifies that the BMC Impact Manager instance send events to the WSCELL event listener residing on the BMC II Web Services Server. Chapter 3 Configuration
45
Defining Propagate rules or propagation event policies for BMC IM cells
For example, if one WSCELL event listener is receiving events from three BMC Impact Manager instances, then each instance must specify a Propagate rule or propagation event policy. Figure 15 on page 46 depicts three BMC Impact Manager instances that are sending events to the WSCELL event listener. You define a Propagate rule or propagation event policy for each instance, specifying the WSCELL event listener as the destination of the event. Figure 15
Event propagation: many instances to one server Impact Manager instance 1 Event Propagation Rule
mcell.dir WSCELL IM instance 1
BMC Impact Integration Web Services Server mcell.dir WSCELL
Impact Manager instance 2
Event Propagation Rule
mcell.dir WSCELL IM instance 2
Impact Manager instance 3
Event Propagation Rule
mcell.dir WSCELL IM instance 3
If multiple WSCELL listeners are receiving events from multiple Impact Manager instances, then for each WSCELL listener you add a Propagate rule or specify a propagation event policy. Figure 16 on page 47 depicts this example.
46
BMC Impact Integration Web Services Server Installation and Configuration Guide
Defining Propagate rules or propagation event policies for BMC IM cells
Figure 16
Event propagation: many instances to many servers
Impact Integration Web Server: Host Name= Zebra
Impact Integration Web Server: Host Name= Giraffe mcell.dir WSCELL
mcell.dir WSCELL
IM Instance 1 IM Instance 2 IM Instance 3
IM Instance 1 IM Instance 2 IM Instance 3
= Event Propagation Rules or Policies
Impact Manager Instance 3
Impact Manager Instance 1 mcell.dir WSCELL:Zebra WSCELL:Giraffe
mcell.dir WSCELL:Zebra WSCELL:Giraffe
IM Instance 1 IM Instance 2 IM Instance 3
IM Instance 3 IM Instance 1 IM Instance 2
Impact Manager Instance 2 In this scenario, BMC IM instances 1, 2, and 3 contain components of the same service model and are sending events to the servers Zebra and Giraffe.
mcell.dir WSCELL:Zebra WSCELL:Giraffe IM Instance 2 IM Instance 1 IM Instance 3
In this scenario, two BMC II Web Services Servers, Zebra and Giraffe, receive events from three BMC Impact Manager instances, all of which contain components of the same service model. Each instance must have a Propagate rule or propagation event policy that specifies the WSCELL event listener or listeners that receive the events. In this example, each instance has to define a rule or policy for both servers. In addition, because all of the cells belong to the same service model, each cell’s mcell.dir file must list the other cells.
Chapter 3 Configuration
47
Defining Propagate rules or propagation event policies for BMC IM cells
TIP When defining your Propagate rule or propagation event policy, be sure to specify the name of the WSCELL entry exactly as it is defined in the mcell.dir file.
Example Propagate rules This section describes sample Propagate rules and describes how to manually add a Propagate rule to the cell’s KB. Refer to the BMC Impact Solutions Knowledge Base Development Reference Guide for additional information about Propagate rules.
NOTE For information on creating a propagation event policy, see the BMC Impact Solutions Event Management Guide.
A Propagate rule might be written as follows: propagate to_WSCELL: EVENT ($EV) to WSCELL END
If you are using the same selector criteria and sending the same events to multiple BMC II Web Services Servers (multiple WSCELL entries WSCELL and WSCELL1, for example), then your Propagate rule might look as follows: propagate to_WSCELL: EVENT ($EV) to_all WSCELL, WSCELL1 END
If you are using different selector criteria to send different events to each BMC II Web Services Server, then you would write a different Propagate rule for each WSCELL. If you are sending different events to WSCELL and WSCELL1, your Propagate rules might look as follows: propagate to_WSCELL: EVENT ($EV) to WSCELL END propagate to_WSCELL1: EVENT ($EV) to WSCELL1 END
48
BMC Impact Integration Web Services Server Installation and Configuration Guide
Defining Propagate rules or propagation event policies for BMC IM cells
You can add any valid Propagate rule to the KB of a BMC Impact Manager instance to propagate events to the BMC II Web Services Server. The task of creating a Propagate rule includes the following procedures that you must perform in order: 1. Create the Propagate rule in a .mrl file. 2. Add the .mrl containing the Propagate rule to the .load file in the rules subdirectory of the BMC Impact Manager instance. 3. Compile the KB of the BMC Impact Manager instance. 4. Restart the BMC Impact Manager instance to initialize the change.
To create a Propagate rule 1 In a text editor, open an existing .mrl file, which you can find under the drive:\IMPACT_SOLUTIONS_HOME\Impact\Server\etc\cellName\kb\rules or IMPACT_SOLUTIONS_HOME/Impact/Server/etc/cellName/kb/rules directory.
2 Remove the text of the existing rule between the last comment symbol (# ) and the END marker.
3 Add the new Propagate rule syntax to the file. You can give the file any name and include comments. Your file would look similar to the following example. #------------------------------------------------------------#Impact Manager #Copyright 1998-2006 BMC Software, Inc. All rights reserved. #Filename : mc_wscell.mrl #------------------------------------------------------------# This rule propagates events to the WSCELL residing on the # BMC II Web Services server. # propagate to_WSCELL: EVENT ($EV) to WSCELL END
NOTE You can add to the KB of the BMC Impact Manager instance any valid Propagate rule that propagates events to the WSCELL.
Chapter 3 Configuration
49
Defining Propagate rules or propagation event policies for BMC IM cells
4 Save the .mrl file, giving it a unique name and making sure that a .txt extension is not added.
5 After you create a Propagate rule in a .mrl file, add the .mrl file with the new Propagate rule to the .load file in the rules subdirectory. See the next procedure.
To add a Propagate rule to the .load file 1 In a text editor, open the .load file under the directory drive:\IMPACT_SOLUTIONS_HOME\Impact\Server\etc\cellName\kb\rules or IMPACT_SOLUTIONS_HOME/Impact/Server/etc/cellName/kb/rules.
2 Add the name of the .mrl file containing the new Propagate rule without the file extension.
3 Save the .load file in the same directory, making sure that a .txt extension is not added.
4 After you add the .mrl file containing the new Propagate rule to the .load file, compile the KB of the BMC Impact Manager instance. See the following procedure.
To compile the Knowledge Base of the BMC Impact Manager Instance 1 In a Command Prompt or in a terminal window, change directory to drive:\IMPACT_SOLUTIONS_HOME\Impact\Server\etc\cellName\kb or IMPACT_SOLUTIONS_HOME/Impact/Server/etc/cellName/kb.
2 Enter the following command: mccomp manifest.kb
The new Propagate rule is added to the KB of the BMC Impact Manager instance.
3 Next, restart the BMC Impact Manager Instance to initialize the change. To restart the BMC Impact Manager instance in Windows 1 In a Command Prompt window, enter the following command: NET STOP mcell_cellName
2 Then enter the start command: NET START mcell_cellName
50
BMC Impact Integration Web Services Server Installation and Configuration Guide
Starting TIBCO-related web services processes (UNIX)
To restart the BMC Impact Manager instance in Linux or Solaris 1 In a terminal window, enter the following command: mkill -n cellName
2 Then enter the start command: mcell -n cellName
Starting TIBCO-related web services processes (UNIX) On UNIX platforms, web services related processes are not started automatically after machine reboot. You or your TIBCO administrator will need to start them manually.
Before you begin Make sure that the ATRIUMCORE_HOME and the TIBCO_HOME variables are defined.
To manually restart the TIBCO web services process 1 Start the EMS server using the following script: $ATRIUMCORE_HOME/wsc/tibco/ems/5.0/bin/startup-ems.sh
2 Start the Management Daemon using the following script: $ATRIUMCORE_HOME/wsc/tibco/managementdaemon/2.0/bin/startupmanagementdaemon.sh
3 If you installed the TIBCO stack and selected the HSQLDB or WebService database server, then you must start the HSQLDB server manually. Navigate to the following directory: $ATRIUMCORE_HOME/wsc/tibco/amx/hsqldb/bin
Then execute the following command: ./amx-db
Chapter 3 Configuration
51
Starting TIBCO-related web services processes (Windows)
4 Start the ActiveMatrix Administrator server using the following script: $ATRIUMCORE_HOME/wsc/tibco/amxadministrator/2.1/bin/ atriumwebservice_atrium.sh
5 Access the TIBCO ActiveMatrix Administrator console (http://hostName:8120/amxadministrator/admin.jsp), and choose Configure an Environment from the Perspectives drop-down menu.
A Under the Nodes pane, select the node to start. B Click the Start button above the Nodes pane.
Starting TIBCO-related web services processes (Windows) After a system reboot, you may not be able to launch the TIBCO ActiveMatrix Administrator console via the URL http://hostName:8120/amxadministrator/admin.jsp. If you unable to connect to the console, you or your TIBCO administrator should first verify in the Services window that the TIBCO ActiveMatrix Administrator Server (atrium web service:atrium) service is running. If not, then start the service. If you cannot start the TIBCO ActiveMatrix Administrator Server (atrium web service:atrium) service and you selected the HSQLDB or WebService database server during the TIBCO stack installation, then verify whether the HSQLDB server is running. If not, then start the HSQLDB server by executing the following command from the Command Prompt window: drive letter:\$ATRIUMCORE_HOME\wsc\tibco\amx\hsqldb\bin > startupHSQLDB.bat
After starting the HSQLDB server, then start the TIBCO ActiveMatrix Administrator Server (atrium web service:atrium) service.
Optional configuration tasks The installation routine sets the default values for port numbers, server attributes, and log files. However, you can modify these values after installation. Table 10 on page 53 lists the optional configuration tasks.
52
BMC Impact Integration Web Services Server Installation and Configuration Guide
Configuring high availability cells for the BMC II Web Services Server
Table 10
Optional configuration tasks
Task
Description
Page
Configuring high availability cells for BMC II Web Services Server
You can configure two cells so that one acts as a secondary server to 53 the primary one in case the primary server fails. In this way, the BMC II Web Services Server can communicate with a secondary cell server until the primary one returns online.
Configuring high availability cells for BMC II Web Services Server in the BPM environment
You can configure an HA pair to accommodate a primary and a backup web services server in the BMC Performance Manager (BPM) environment. You must install a separate TIBCO stack for each BMC II Web Services Server instance.
56
Updating default port numbers post installation
You can update the HTTP server and WSCELL port numbers after installation if a port number conflict develops.
58
Default logging
You can customize the different log files that the BMC II Web Services Server and TIBCO platform use.
61
Setting substitution variables
Through the TIBCO ActiveMatrix Administrator console, you can define substitution variables.
65
Configuring high availability cells for the BMC II Web Services Server NOTE Refer to the BMC Impact Solutions Infrastructure Administration guide for detailed information about high availability (HA) implementation.
To maximize availability, BMC recommends that you install your primary cell on one computer and your secondary cell on a different computer. Both primary and secondary cells should be installed and running on different images of the same operating system. Your HA implementation can take many forms, but two likely ones are depicted in the following figures. Figure 17 on page 54 shows a scenario in which the BMC II Web Services Server and the primary cell server of the HA pair are installed on the same system. The secondary cell server of the HA pair is installed on a second system. In this scenario, because the cell both sends and receives events to and from the BMC II Web Services Server, both primary and secondary cell servers must have a WSCELL entry in their respective mcell.dir files. (If the cell servers were only receiving events from the BMC II Web Services Server, then they would not need the WSCELL entry.)
Chapter 3 Configuration
53
Configuring high availability cells for the BMC II Web Services Server
Figure 17
HA implementation scenario: primary cell server and web server on same system System A: BMC Web Services Server and primary cell server mcell.dir of the BMC II Web Services Server on system A. The mcell.dir includes the HA cell Alphonse that resides on system A, with which the web services server communicates. cell cell cell
local WSCELL Alphonse
MC MC MC
localHost:1828 127.0.0.1:19999 systemA:1828 systemB:1828 [HA pair]
mcell.dir of the primary HA cell Aphonse that communicates with BMC II Web Services Server and resides on system A. cell cell
WSCELL Alphonse
MC MC
systemA:19999 systemA:1828 systemB:1828 [HA pair]
Note: Because BMC II Web Services Server sends AND receives events from the cell, the cell’s mcell.dir file requires a WSCELL entry.
System B: the secondary cell server of the HA pair mcell.dir of the secondary cell server. It includes a WSCELL entry to ensure that the secondary cell server, when active, can both send and receive events to the BMC II Web Services Server on system A. cell cell
WSCELL Alphonse
MC MC
systemA:19999 systemA:1828 systemB:1828 [HA pair]
Figure 18 on page 55 shows a scenario in which the BMC II Web Services Server and the primary cell server of the HA pair are installed on different systems. The secondary cell server of the HA pair is installed on a third system. As in the previous scenario, the cell both sends and receives events to and from the BMC II Web Services Server. Consequently, both primary and secondary cell servers must have a WSCELL entry in their respective mcell.dir files.
54
BMC Impact Integration Web Services Server Installation and Configuration Guide
Configuring high availability cells for the BMC II Web Services Server
Figure 18
HA implementation scenario: primary cell server and web server on different systems System 1: BMC II Web Services Server mcell.dir of the BMC II Web Services Server residing on system 1. It specifies the HA cell, Alphonse, which resides on system A. cell cell cell
local WSCELL Alphonse
MC MC MC
localHost:1828 127.0.0.1:19999 systemA:1828 systemB:1828 [HA pair]
System A: primary cell server mcell.dir of the primary cell server Alphonse, residing on system A, that communicates with BMC II Web Services Server. cell cell
WSCELL Alphonse
MC MC
system1:19999 systemA:1828 systemB:1828 [HA pair]
Note: Because BMC II Web Services Server sends AND receives events from the cell, the cell’s mcell.dir file requires a WSCELL entry. System B: secondary cell server of the HA pair mcell.dir of the secondary cell server, which resides on system B. It includes a WSCELL entry to ensure that the secondary cell server, when active, can both send and receive events to the BMC II Web Services Server on system 1. cell cell
WSCELL Alphonse
MC MC
system1: 19999 systemA:1828 systemB:1828 [HA pair]
Follow these guidelines to install and configure a primary and a secondary cell in an HA pair: ■
Be sure to install BMC Impact Manager on the two different computers that host the cell servers. They must be installed on the same operating system.
■
Use the BMC Impact Solutions installation routine to install the HA cells. When using the installation routine, the mcell.dir and mcell.conf files of the respective cells are updated automatically.
■
Configure the mcell.dir file of the BMC II Web Services Server to accommodate the HA cell configuration. See Figure 17 on page 54 and Figure 18 on page 55 for examples.
■
Restart the cell servers.
Chapter 3 Configuration
55
Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment
NOTE Refer to the BMC Impact Solutions Infrastructure Administration guide for detailed information about high availability (HA) implementation.
Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment The same rules for configuring high availability cells for the BMC II Web Services Server also apply to the BMC Performance Manager (BPM) environment. BPM does add the extra feature of having a backup BMC II Web Services Server. Both the primary and backup web services servers connect to the same primary cell server. The HA configuration is specified in the mcell.dir files of the primary and secondary cell servers.
NOTE You must install a TIBCO stack for each BMC II Web Services Server instance that you install.
Figure 19 on page 57 depicts a recommended HA cell configuration where BPM has specified a primary and a backup web services server. Note that the cell does not have to reside on the same system as the web services server.
56
BMC Impact Integration Web Services Server Installation and Configuration Guide
Guidelines for configuring attributes of the BMC II Web Services Server
Figure 19
HA implementation scenario for BPM and BMC II Web Services Server
BMC Performance Manager System 1: Primary BMC II Web Services Server, which communicates with HA cell Alphonse
mcell.dir of primary BMC II Web Services Server
cell cell cell
localhost:1828 MC 127.0.0.1:19999 MC systemA:1828 systemB:1828 MC
local WSCELL Alphonse
System 2: backup BMC II Web Services Server, which also communicates with HA cell Alphonse
mcell.dir of secondary BMC II Web Services Server
cell cell cell
System A: Primary HA cell server Alphonse
local WSCELL Alphonse
MC MC MC
mcell.dir of secondary cell server
Alphonse
MC systemA:1828 systemB:1828
localhost:1828 127.0.0.1:19999 systemA:1828 systemB:1828
System B: Secondary HA cell server Alphonse
mcell.dir of primary cell server
cell
cell
Alphonse
systemA:1828 systemB:1828 MC
Guidelines for configuring attributes of the BMC II Web Services Server You or your TIBCO administrator can configure some attributes of the BMC II Web Services Server through the TIBCO ActiveMatrix Administrator GUI. For example, as described under “Updating default port numbers post installation” on page 58, you can modify the default port number and install a new HTTP server through the GUI. You can also modify attributes such as the following: ■ ■
■
substitution variables of the ImpactManagerService service assembly logging configurations for the ImpactManagerService service assembly or for the iiws_node services associated with the ImpactManagerService service assembly
Chapter 3 Configuration
57
Updating default port numbers post installation
Apart from modifying attributes in the TIBCO ActiveMatrix Administrator console, you can modify the following BMC II Web Services Server attributes in the installDirectory\webServices\conf\iiws.conf file: ■ ■ ■ ■
MessageListenerCellName MaxReturnEventListSize IIAPISelectorFile ServerCacheDir
See “Configuration file” on page 86 for more information.
Updating default port numbers post installation If the default ports are being used by another process, you must change the default port numbers so that the BMC II Web Services Server and client can communicate with each other and with connected BMC Impact Manager instances. You change the default port of the HTTP transport server through the TIBCO ActiveMatrix Administrator console. You change the WSCELL default port by manually editing the BMC Impact Manager mcell.dir file.
To change the default HTTP_server port number on the BMC Impact Integration Web Services Server The HTTP transport server specifies the port number through which the BMC II Web Services client exchanges request-response messages with the BMC II Web Services Server.
NOTE If you are unfamiliar with the TIBCO ActiveMatrix Administrator console, ask your TIBCO administrator to help with this procedure. You will need to have permission to make these changes.
1 Launch the TIBCO ActiveMatrix Administrator through the URL address: for example, http://hostName:8120/amxadministrator/admin.jsp. Figure 20 on page 59 shows the port number associated with the BMC II Web Services.
58
BMC Impact Integration Web Services Server Installation and Configuration Guide
Updating default port numbers post installation
Figure 20
TIBCO ActiveMatrix Administrator: port number example
2 Choose Configure Enterprise Assets from the Perspective drop-down menu, and select the Shared Resources Definitions option at the top row of the panel. The Edit pane is displayed for the HTTP_Server_IIWS entry.
3 Choose Edit to modify the Port number entry, and save the updated value. 4 Restart the iiws_node from the Configure an Environment perspective. Alternative procedure Instead of changing the port number of the current HTTP server, you can add another HTTP server and assign it a different port number. Select New => HTTP Server to open the Edit panel to add a new HTTP server. See, for example, the HTTP server Edit panel in Figure 21 on page 60.
Chapter 3 Configuration
59
Updating default port numbers post installation
Figure 21
TIBCO ActiveMatrix Administrator: HTTP server example
Restart the iiws_node from the Configure an Environment perspective after adding the new HTTP server configuration.
To Change the Port Number of the WSCELL event listener The WSCELL is described in “WSCELL event listener” on page 15. Each instance of the BMC II Web Services Server must have an associated WSCELL entry.
1 In a text editor, open the mcell.dir file located under installDirectory\webServices\conf directory path.
2 Change the port number. 3 Save and close the mcell.dir file. 4 From the TIBCO ActiveMatrix Administrator console, restart the ImpactManagerService service assembly from the Deploy to an Environment perspective.
60
BMC Impact Integration Web Services Server Installation and Configuration Guide
Modifying log files
Alternatively, execute the iiws_node restart CLI from the directory path installDirectory\webServices\bin, as in the following example: installDirectory\webServices\bin iiws_node restart
Modifying log files You can modify log files of the BMC Impact Integration Web Services Server, and you can modify the TIBCO ActiveMatrix logging configurations for a selected service assembly or node through the TIBCO ActiveMatrix Administrator console .
To modify the default BMC II Web Services Server log By default, the BMC II Web Services Server uses the installDirectory\webServices\conf\trace.log to record its activities. A BMC II Web Services Server administrator can modify the trace.log parameters such as log file name and directory location in the iiws.conf file found under installDirectory\webServices\conf. The administrator can change the default logging level in the iiws.trace file also found under the same directory path.
1 In a text editor, open the iiws.conf file. The trace parameters are contained in the following stanza, depicted in the following example diagram: Trace=Yes TraceSrc=No TraceConfigFileName=iiws.trace LocaleConfigFileName=C:\Program Files\BMC\IIWS/locale/iiws.load TraceDefaultFileName=trace.log TraceFileSize=1024000 TraceFileHistory=1 TraceFileAppend=No
2 Modify the configuration parameters. Refer to “Configuration file parameters” on page 86 for a description of the configuration parameters. Skip to Step 5 if you are done with your changes.
3 To change the level of logging detail, open the iiws.trace file. You can modify the default values, which are depicted in the following example: ALL ALL stderr ALL VERBOSE no
4 Modify the file according to the instructions in the BMC Impact Solutions Infrastructure Administration guide. You can refer also to “Editing the trace configuration file” on page 100 for more information.
Chapter 3 Configuration
61
Modifying log files
5 From the TIBCO ActiveMatrix Administrator console, restart the ImpactManagerService service assembly from the Deploy to an Environment perspective. Alternatively, execute the iiws_node restart CLI from the directory path installDirectory\webServices\bin, as in the following example: installDirectory\webServices\bin iiws_node restart
NOTE The BMC II Web Services Server temporarily keeps client-requested events in the installDirectory\webServices\log subdirectory for non-reliable subscriptions and in the installDirectory\webServices\cache subdirectory for reliable subscriptions. The events remain in the log or cache folders until the client consumes them or the client unsubscribes from the server.
To modify TIBCO ActiveMatrix logging configurations You can modify the logging configuration for a selected service assembly or a selected node. In the TIBCO ActiveMatrix Administrator console, you modify the logging configuration in the corresponding perspective of the service assembly (Deploy to an Environment) or the node (Configure an Environment). The logging configuration parameters are similar for both the service assembly and the node. The difference lies in the activities that you can choose to log. This example procedure illustrates how to modify the logging configuration of a service assembly.
1 Launch the TIBCO ActiveMatrix Administrator through the URL address: for example, http://hostName:8120/amxadministrator/admin.jsp.
2 Choose Perspective => Deploy to an Environment. 3 Select the service assembly. 4 Select Logging Configurations under the General Settings tab. The currently monitored object is displayed, as shown in the example of Figure 22 on page 63.
62
BMC Impact Integration Web Services Server Installation and Configuration Guide
Modifying log files
Figure 22
TIBCO ActiveMatrix Administrator console: logging configurations
5 To add other objects to be logged, click Service Unit Logging to open a dialog box from where you can select the service units to log. These objects are added to the list of objects in the Logging Configurations list, as shown in the example of Figure 23 on page 64.
Chapter 3 Configuration
63
Modifying log files
Figure 23
TIBCO ActiveMatrix Administrator console: objects to log
6 To modify basic configuration attributes, do the following: ■
To sort the list of objects alphabetically, click the arrow in the Object column header.
■
To choose among severity levels, click the arrow in the Severity value field to display the choices in the drop-down list.
7 Save your changes. TIP If you are unfamiliar with the TIBCO platform and wish to perform other, more advanced logging tasks, you can check the TIBCO documentation or with your TIBCO administrator.
By default, the TIBCO ActiveMatrix log file is stored under TIBCO_HOME\amx\data\environmentName\nodeName\log, where TIBCO_HOME references the file path wsc\tibco. The default log file name is stdOut.log.
64
BMC Impact Integration Web Services Server Installation and Configuration Guide
Setting substitution variables
Setting substitution variables You or your TIBCO administrator can assign values to the following substitution variables. Substitution variables are a special feature of the TIBCO ActiveMatrix Administrator console. They specify constants that can be used throughout the service assembly process. Substitution variable name
Value
full path to the LIBPATH variable
the IIWS shared library; for example: installDirectory\webServices\lib
full path to the LIBNAME variable
name of the IIWS shared library: IMService
full path to the IIWS_ROOT variable the configuration home directory; for example: installDirectory\webServices
You can modify these variables under the corresponding perspective of the service assembly (Deploy to an Environment). After modifying these variables, restart the corresponding service assembly.
Advanced task You should probably be familiar with managing web services, the BMC Impact Manager environment, and the TIBCO platform before installing multiple instances of the BMC II Web Services Server across multiple host systems.
Installing multiple instances of the BMC II Web Services Server on different host systems Depending on your deployment strategy and performance loads, you may want to install and run multiple instances of the BMC II Web Services Server service on different host systems. For example, you can connect each service instance to different clients and BMC Impact Manager instances. A client can subscribe to different event types by connecting to different BMC II Web Services Servers. To install another instance of the BMC II Web Services Server service, repeat the installation sequence that is appropriate for the platform. For each BMC II Web Services Server instance that you install, you must also install the TIBCO stack from the BMC Atrium Core 7.5.00 patch 2 download before installing the server.
Chapter 3 Configuration
65
Installing multiple instances of the BMC II Web Services Server on different host systems
NOTE BMC II Web Services Server 7.3.01 does not support the installation of multiple BMC II Web Services Server instances on the same host system.
66
BMC Impact Integration Web Services Server Installation and Configuration Guide
Chapter
4
BMC Impact Integration Web Services Server administration 4
This chapter describes configuration files that affect how the underlying BMC APIs interact with the BMC Impact Manager instances to which they connect. This appendix tells how to update the selector file (*.selector), the configuration file (*.conf), and the trace file (*.trace). It provides a summary of the mcell.dir file. This chapter is addressed primarily to the application administrator who is knowledgeable about the configuration files of BMC Impact Manager and BMC II Web Services Server. The administrator should also be familiar with the TIBCO ActiveMatrix Administrator console. This appendix describes the following topics: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 How the BMC II Web Services Server reads selector files and parameters . . . . . . . . 69 Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Chapter 4
BMC Impact Integration Web Services Server administration
67
Overview
Overview Administering the BMC II Web Services Server consists of typical server administration tasks and two tasks unique to the BMC II Web Services implementation: managing the selector file (iiws.selector) and the configuration file (iiws.conf). The BMC II Web Services Server reads both files at startup. Both files are stored under installDirectory/webServices/conf. The selector file is crucial in determining which events the subscribing clients receive. When you are first setting up and practicing with the BMC II Web Services Server toolkit, you do not need to modify the default iiws.selector file. You can issue subscription requests that include the selector name Always matches for the $ClassName “Event”. Using this selector, your client receives all events propagating from the BMC Impact Manager instances. Later, as you define your client more carefully, you will probably want to modify the selector file. The iiws.conf is preconfigured so that you do not have to modify the iiws.conf to run the BMC II Web Services Server. Later, as you learn more about your integration needs, you can modify the parameters in the configuration file. Modifying the selector file is a task best performed by a BMC II Web Services Server administrator who has administered the BMC Impact Manager product. The same administrator can also manage the configuration file, updating the parameters as required. The mcell directory also contains four supplemental selector files. You can enable one or more of these files to improve the speed and efficiency of event filtering between the BMC II Web Services Server and the cell. These selector files do their processing in the background and, unlike the iiws.selector file, are not loaded by the BMC II Web Services Server at startup.
Starting server instances The web services server administrator is responsible for starting and maintaining the server. To launch the server, follow the instructions in “Starting and stopping the BMC II Web Services Server” on page 34.
68
BMC Impact Integration Web Services Server Installation and Configuration Guide
Selector file overview
Selector file overview The BMC Impact Integration APIs use the selector file to define groups of criteria (called selectors) that are used to identify and select messages which propagate from BMC Impact Manager instances. Messages that match all the criteria in a selector become available to the BMC Impact Integration Web Services’ publish-subscribe and polling mechanisms. The selector file is a case-insensitive text file. The selector file is required for BMC Impact Integration Web Services’ clients that receive events from BMC Impact Manager instances.
NOTE The selector file is not required for web service clients that only send events or data or that only launch queries.
A default selector file, iiws.selector, is stored under the installDirectory/webServices/conf subdirectory.
How the BMC II Web Services Server reads selector files and parameters The BMC Impact Manager cell uses selectors to match incoming events and to make them available to subscribing clients. When programming the web service client, you specify the selector name to invoke in the subscription request (bmciiws_subscribe_reliable). The subscription call identifies the client and the selector name to the BMC II Web Services Server. The BMC II Web Services Server stores this information in a subscription table, in which selector entry names are mapped to specified client IDs. During runtime, the BMC II Web Services Server loads the selector file specified by the iiws.conf file. (Only one selector file is loaded per session.) The specified selector file applies to all the messages that propagate from all the BMC Impact Manager cells to which the server is connected. Multiple clients can subscribe to the same selector entry in a web services session. Conversely, a single web service client can subscribe to different selectors in the same session by initiating multiple subscription calls, each specifying a different selector name.
Chapter 4
BMC Impact Integration Web Services Server administration
69
Selector file description
NOTE Whenever a client subscribes to multiple selectors, it runs the risk of receiving duplicate messages from a cell. The same message can satisfy the different criteria specified by each selector name and be forwarded to the subscribing client.
As BMC Impact Manager events propagate to the BMC II Web Services Server, the server accesses the specified selector file, which is loaded in memory. When a BMC Impact Manager message matches a selector parameter in the selector file, the server looks into the subscription table to get the clients that have invoked subscriptions with the matching selector parameter name. The server dispatches the event to all web service clients that have subscribed to the selector parameter name.
NOTE When an incoming BMC Impact Manager event arrives, BMC II Web Services Server checks the event against all selectors in the selector set of the file. For each match of selector with event, it checks whether there is a subscription request from a subscribing web service client. It dispatches the event to each client that has a subscription with a matching selector entry.
Selector file description The following topics describe the structure and content of message selector set files as implemented by the BMC APIs.
Characteristics Message selector set files have the following characteristics:
70
■
Message selector set file criteria are not case sensitive.
■
The naming convention for message selector set files is integrationName.selector.
■
Message selector set file syntax is checked when the message selector set file is loaded. If the message selector set file contains problematic syntax, the BMC II C API bmcii_loadSelectorSet() function will fail.
■
The contents of a message selector set file comprise a message selector set. The message selector set can contain one or more message selectors. However, a message selector set file can contain only one message selector set.
■
Each message selector in a message selector set must have a unique name. However, different message selector sets can have message selectors with identical names.
BMC Impact Integration Web Services Server Installation and Configuration Guide
Characteristics
■
When a message selector set file is called by the BMC II C API bmcii_matchSelectorSet() function, it is scanned from beginning to end. The selection process for the message stops the first time that a parameter in a message selector is matched to a parameter value in a message. Once a match is made, the remaining message selectors in a set are ignored. If the bmcii_matchSelectorSetAll() function is called, the function continues to scan after a matching message selector is identified.
■
Because the message selector sets are scanned from beginning to end, the order of message selectors in a set and lines within a message selector are important to optimizing the matching process.
■
The $doselector function allows you to include message selectors and subselectors within a selector set. Message selectors and subselectors further refine the selector criteria.
■
The $doselector function invokes message subselectors.
■
The relationship between the criteria described in successive lines of a single stanza in a message selector is AND, unless otherwise indicated.
■
The message selector file supports the logical operators OR, AND, &&, and ||.
■
A message selector set can contain multiple stanzas of message selector criteria, nested one level deep. These multiple stanzas of message selector criteria are referred to as message selector groups. The logical relation between the groups can be expressed through an AND, OR, &&, or || connector.
■
Each line in a message selector contains only one message selector criterion.
■
The message selector file supports the following comparison operators ■ ■ ■ ■
greater-than (>) greater-than or equal to (>=) less-than (
