BMC Impact Integration Web Services Server Installation ...atmgmicrosoft.free.fr/depot/at/BMC doc/BMC Impact Integration Web... · Starting TIBCO-related web services processes

www.bmc.com

BMC Impact Integration Web Services ServerInstallation and Configuration Guide

Supporting

BMC Impact Integration Web Services Server v.7.3.01

June 2009

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 INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000

© 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 legendU.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.”

http://www.bmc.com

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:<yourSupportContractID>, 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

http://www.bmc.com/support

mailto:[email protected]

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



ContentsChapter 1 Introduction 11

Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . 12New BMC Impact Integration Web Services Server platform . . . . . . . . . . . . . . . . 12Version 7.3.01 changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13BMC Impact Integration C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15How a send request is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16How the receive feature works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2 Installation 19

Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Atrium Core prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Compatible web services toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . 21

Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22How to install BMC II Web Services Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Obtaining the prerequisite BMC Atrium Core 7.5.00 patch 2. . . . . . . . . . . . . . . . . 22Installing the BMC II Web Services server (Windows or UNIX) . . . . . . . . . . . . . . 22BMC II Web Services Server Installation directory contents . . . . . . . . . . . . . . . . . 24Location of TIBCO documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Verifying the status of the related web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Before sending events to BMC Impact Manager cells . . . . . . . . . . . . . . . . . . . . . . . 30

How to uninstall BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 3 Configuration 33

Configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 34

TIBCO ActiveMatrix Administrator console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34iiws_node CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Contents 5

Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Synchronizing BMC II Web Services Server and BMC IM cell connections . . . . . 38mcell.dir configurations for different server implementations . . . . . . . . . . . . . . . . 40Adding WSCELL entries to BMC Impact Manager mcell.dir files . . . . . . . . . . . . . 42Adding BMC Impact Manager instance entries to the BMC II Web Services

Server’s mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Troubleshooting tip: BMC II Web Services Server fails to reconnect. . . . . . . . . . . 45Defining Propagate rules or propagation event policies for BMC IM cells. . . . . . 45Starting TIBCO-related web services processes (UNIX) . . . . . . . . . . . . . . . . . . . . . 51Starting TIBCO-related web services processes (Windows) . . . . . . . . . . . . . . . . . . 52

Optional configuration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Configuring high availability cells for the BMC II Web Services Server . . . . . . . . 53Configuring HA cells for BMC II Web Services Server in the BMC Performance

Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Guidelines for configuring attributes of the BMC II Web Services Server . . . . . . 57Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Modifying log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Setting substitution variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Advanced task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Installing 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69How the BMC II Web Services Server reads selector files and parameters . . . . . . . . . 69Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

mcell.dir file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Index 103


FiguresComponents of the BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . 12Welcome screen of the BMC Impact Integration Web Services 7.3.01 Installer . . . . . 23TIBCO ActiveMatrix Administration console: Service Assemblies . . . . . . . . . . . . . . . 27TIBCO ActiveMatrix Administrator console: iiws_node . . . . . . . . . . . . . . . . . . . . . . . 28TIBCO ActiveMatrix Administrator console: node containers . . . . . . . . . . . . . . . . . . 29TIBCO ActiveMatrix Administrator console: Shared resources: HTTP_Server . . . . 29TIBCO ActiveMatrix console: HTTP_Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30BMC II Web Services Server uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31TIBCO ActiveMatrix Administrator console: Service Assemblies . . . . . . . . . . . . . . . . 35TIBCO ActiveMatrix Administrator console: Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 36mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Event propagation: many instances to one server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Event propagation: many instances to many servers . . . . . . . . . . . . . . . . . . . . . . . . . . 47HA implementation scenario: primary cell server and web server on same system 54HA implementation scenario: primary cell server and web server on different

systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55HA implementation scenario for BPM and BMC II Web Services Server . . . . . . . . . 57TIBCO ActiveMatrix Administrator: port number example . . . . . . . . . . . . . . . . . . . . 59TIBCO ActiveMatrix Administrator: HTTP server example . . . . . . . . . . . . . . . . . . . . 60TIBCO ActiveMatrix Administrator console: logging configurations . . . . . . . . . . . . 63TIBCO ActiveMatrix Administrator console: objects to log . . . . . . . . . . . . . . . . . . . . . 64Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Sample trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Figures 7


TablesComponents that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Compatible toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Location of mcell.dir Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39mcell.dir configurations for queries and for sending events . . . . . . . . . . . . . . . . . . . . 40mcell.dir configurations for receiving events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Tables 9


C h a p t e r 1
1 Introduction
This chapter presents the following topics:

Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . 12New BMC Impact Integration Web Services Server platform . . . . . . . . . . . . . . . . 12Version 7.3.01 changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13BMC Impact Integration C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15How a send request is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16How the receive feature works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 1 Introduction 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

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.

WSDL FileService interface fileBindingPort typeMessageType

Web ServicesToolkit

Third-partyclient(ServiceRequestor)

Web Services Server (TIBCO Foundation)

ImpactIntegrationWeb ServiceAPIs

C APIsBMC ImpactManagercell or cells

SOAPMessages

SynchronousorAsynchronous

Service Provider

EncryptedCommunications


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.


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.

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.

NOTE The BMC II Web Services Server uses encrypted communications. User authentication is not available.


Features of the BMC II Web Services Server

Features of the BMC II Web Services ServerThis 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.

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.)

cell local mc localhost:1828cell WSCELL mc 127.0.0.1:19999


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.

■ 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.

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.


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.

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.

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.


Intended audience

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 audienceThe 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.

NOTE IIWS_ROOT is one of the TIBCO substitution variables. Its default value is installDirectory\webservices.


http://communities.bmc.com/communities/community/bmcdn

C h a p t e r 2
2 Installation
This chapter presents the following topics:

Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Compatible web services toolkits for building clients . . . . . . . . . . . . . . . . . . . . . . . 21

Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22How to install BMC II Web Services Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

BMC II Web Services Server Installation directory contents . . . . . . . . . . . . . . . . . 24Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Verifying the status of the related web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Before sending events to BMC Impact Manager cells . . . . . . . . . . . . . . . . . . . . . . . 30

How to uninstall BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31


Installation package contents

Installation package contentsThe 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.


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.

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 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

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


Disk space requirements

Disk space requirements

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/web/?cacheid=76981cd6

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.

UNIX Windows

TIBCO Stack/Atrium Core 3045 MB 3045 MB

BMC II Web Services Server 50 MB 50 MB

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.


http://support.bmc.com/arsys/apps/remcspenu.bmc.com/Patch/CS%3APatch/web/?cacheid=76981cd6

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 platform-specific 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.


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

■ 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


Location of TIBCO documentation

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-installationTo 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

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

Table 5 Directory contents (part 2 of 2)

Directory Description


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

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

■ 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

NOTE The string “http://hostName:portNumber/impactmanager” is case sensitive.



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.



Figure 4 TIBCO ActiveMatrix Administrator console: iiws_node

Ensure that the iiws_node has the status “Running.”

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.

NOTE The iiws_node is not dependent on the atrium_node. The atrium_node can be stopped without impacting the iiws_node.



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.


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.


How to uninstall BMC II Web Services Server

How to uninstall BMC II Web Services ServerYou 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


How to uninstall BMC II Web Services Server


C h a p t e r 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 34

TIBCO ActiveMatrix Administrator console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34iiws_node CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Synchronizing BMC II Web Services Server and BMC IM cell connections. . . . . 38mcell.dir configurations for different server implementations . . . . . . . . . . . . . . . 40Adding WSCELL entries to BMC Impact Manager mcell.dir files . . . . . . . . . . . . 42Adding BMC Impact Manager instance entries to the BMC II Web Services

Server’s mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 45Defining Propagate rules or propagation event policies for BMC IM cells . . . . . 45Starting TIBCO-related web services processes (UNIX) . . . . . . . . . . . . . . . . . . . . . 51Starting TIBCO-related web services processes (Windows) . . . . . . . . . . . . . . . . . . 52

Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Configuring high availability cells for the BMC II Web Services Server . . . . . . . 53Configuring HA cells for BMC II Web Services Server in the BMC Performance

Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Guidelines for configuring attributes of the BMC II Web Services Server . . . . . . 57Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Modifying log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Setting substitution variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Advanced task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Installing multiple instances of the BMC II Web Services Server on different host

systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65


Configuration overview

Configuration overviewConfiguring 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.



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.



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:

■ mcell.dir■ iiws.conf■ iiws.trace■ selector files


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

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:

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.

installDirectory\webServices\bin iiws_node restart


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 tasksConfiguring the BMC II Web Services Server consists of the following required tasks that you perform by manually editing BMC Impact Manager configuration files:

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:

■ one for its WSCELL event listener ■ the other for any BMC IM cells with which it communicates

Table 6 Required configuration tasks

Task Description Page


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.

38

Defining Propagate rules or propagation event policies for BMC IM cells

To receive events (aside from state change events) from BMC IM cells, you must define Propagate rules or propagation event policies that specify the WSCELL entry of the BMC II Web Services Server.

45



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

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.

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:

Similarly, each subsequent cell’s mcell.dir would also reference the other cells in the service model.

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 Location of mcell.dir Files

Operating System BMC Impact Manager instanceBMC Impact Integration Web Services Server instance

Windows MCELL_HOME\etc drive:\installDirectory\webServices\conf

Solaris, Linux MCELL_HOME/etc installDirectory/webServices/conf

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellA MC myIMComputer:1828cell cellB MC myIMComputer1:1828cell cellC MC myIMComputer2:1828cell cellD MC myIMComputer3:1828


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.

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 mcell.dir example: BMC II Web Services Server

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.

Table 8 mcell.dir configurations for queries and for sending events

Purpose of BMC II Web Services Server instance

mcell.dir entries: BMC II Web Services Server instance mcell.dir entries: BMC IM instances

To query events, data, or a service model

To send events

■ 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

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell WSCELL MC myWSComputer:19999cell cellConnect MC myIMComputer:1828cell cellConnect 1 MC secondIMComputer:1828cell cellConnect 2 MC thirdIMComputer:1828



Figure 12 mcell.dir example: BMC IM cell

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.

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

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell cellConnect 1 MC secondIMComputer:1828cell cellConnect 2 MC thirdIMComputer:1828

Table 9 mcell.dir configurations for receiving events

Purpose of BMC II Web Services Server instance

mcell.dir entries: BMC II Web Services Server instance mcell.dir entries: BMC IM instances

To receive events from connected cells

■ its local WSCELL entry■ the cell or cells that it

communicates with, including all cells that comprise the service model

■ 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

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.


Adding WSCELL entries to BMC Impact Manager mcell.dir files

Figure 13 mcell.dir example: BMC II Web Services Server

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 mcell.dir example: BMC IM cell

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.


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.





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.

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:

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:

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.

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999cell WSCELL1 MC secondWSComputer:19999cell WSCELL2 MC thirdWSComputer:19999

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell cellConnect MC myIMComputer:1828cell WSCELL MC myWSComputer:19999cell WSCELL1 MC myWSComputer:20000cell WSCELL2 MC myWSComputer:20001


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:

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.

<Type> <Name> <EncryptionKey> <IPAddress:Port>cell WSCELL MC 127.0.0.1:19999cell cellConnect MC myIMComputer:1828cell cellConnect1 MC myIMComputer1:1828cell cellConnect2 MC myIMComputer2:1828cell cellConnect3 MC myIMComputer3:1828


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:

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.


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.




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

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.

Impact Manager instance 1



mcell.dir

mcell.dir

mcell.dir

WSCELL

IM instance 1

WSCELL

WSCELL

IM instance 2

IM instance 3

BMC Impact Integration

mcell.dirWSCELL

Web Services Server

Event Propagation Rule





Figure 16 Event propagation: many instances to many servers

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.

Impact Integration Web Server:Host Name= Zebra

Impact Integration Web Server:Host Name= Giraffe

Impact Manager Instance 1



mcell.dirWSCELL

IM Instance 1IM Instance 2IM Instance 3

mcell.dirWSCELL


mcell.dirWSCELL:ZebraWSCELL:Giraffe






= EventPropagationRules or Policies

In this scenario, BMC IMinstances 1, 2, and 3 containcomponents of the same servicemodel and are sending eventsto the servers Zebra and Giraffe.



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.

A Propagate rule might be written as follows:

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:

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:

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.

NOTE For information on creating a propagation event policy, see the BMC Impact Solutions Event Management Guide.

propagate to_WSCELL:EVENT ($EV)to WSCELL

END

propagate to_WSCELL:EVENT ($EV)to_all WSCELL, WSCELL1

END

propagate to_WSCELL:EVENT ($EV)to WSCELL

ENDpropagate to_WSCELL1:

EVENT ($EV)to WSCELL1

END



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.



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


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/startup-managementdaemon.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


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 tasksThe 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.


Configuring high availability cells for the BMC II Web Services Server


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.)

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 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.

53

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

NOTE Refer to the BMC Impact Solutions Infrastructure Administration guide for detailed information about high availability (HA) implementation.



Figure 17 HA implementation scenario: primary cell server and web server on same system

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.

System A: BMC Web Services Server and primary cell servermcell.dir of the BMC II Web Services Server on system A. The mcell.dir includes the HA cellAlphonse that resides on system A, with which the web services server communicates.

<Type>cellcellcell

<Name>localWSCELLAlphonse

<EncryptionKey>MCMCMC

<IP address:port>localHost:1828127.0.0.1:19999

systemA:1828 systemB:1828

mcell.dir of the primary HA cell Aphonse that communicates with BMC II Web Services Serverand resides on system A.

<Type>cellcell

<Name>WSCELLAlphonse

<EncryptionKey>MCMC

<IP address:port>systemA:19999


Note: Because BMC II Web Services Server sends AND receives events from the cell, the cell’smcell.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 WebServices Server on system A.

<Type>cellcell

<Name> <EncryptionKey>MCMC

WSCELLAlphonse

<IP address:port>systemA:19999


[HA pair]

[HA pair]

[HA pair]



Figure 18 HA implementation scenario: primary cell server and web server on different systems

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.

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.

<Type>cellcellcell

<Name> <EncryptionKey> <IP address: port>localWSCELLAlphonse

MCMCMC

localHost:1828127.0.0.1:19999


System A: primary cell server

mcell.dir of the primary cell server Alphonse, residing on system A, that communicates withBMC II Web Services Server.

Note: Because BMC II Web Services Server sends AND receives events from the cell, the cell’smcell.dir file requires a WSCELL entry.

System B: secondary cell server of the HA pairmcell.dir of the secondary cell server, which resides on system B. It includes a WSCELL entryto ensure that the secondary cell server, when active, can both send and receive events to the BMC II Web Services Server on system 1.

<Type>cellcell


<EncryptionKey>MCMC

<IP address:port>system1:19999


<Type>cellcell


<EncryptionKey>MCMC

<IP address: port>system1: 19999


[HA pair]

[HA pair]

[HA pair]


Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment

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.

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.

NOTE Refer to the BMC Impact Solutions Infrastructure Administration guide for detailed information about high availability (HA) implementation.

NOTE You must install a TIBCO stack for each BMC II Web Services Server instance that you install.


Guidelines for configuring attributes of the BMC II Web Services Server

Figure 19 HA implementation scenario for BPM and BMC II Web Services Server

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

<Type>cellcellcell

<Name>localWSCELLAlphonse

<EncryptionKey>MCMCMC

<IPAddress:Port>localhost:1828127.0.0.1:19999


<Type> <Name> <EncryptionKey> <IPAddress:Port>cellcellcell

localWSCELLAlphonse

MCMCMC

localhost:1828127.0.0.1:19999


<Type> <Name> <EncryptionKey> <IPAddress:Port> <Type> <Name> <EncryptionKey> <IPAddress:Port>cell Alphonse MC systemA:1828 systemB:1828 systemA:1828 systemB:1828MCAlphonsecell

BMC Performance ManagerSystem 1: Primary BMC II Web ServicesServer, which communicates with HA cell Alphonse

System 2: backup BMC II Web Services Server, whichalso communicates with HA cell Alphonse

System A: Primary HA cell server AlphonseSystem B: Secondary HA cell server Alphonse

mcell.dir of primary BMC II Web Services Server BMC II Web Services Servermcell.dir of secondary

mcell.dir of primary cell server mcell.dir of secondary cell server



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.


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.

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.

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.



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.



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.



Modifying log files


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:

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:

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.


Trace=YesTraceSrc=NoTraceConfigFileName=iiws.traceLocaleConfigFileName=C:\Program Files\BMC\IIWS/locale/iiws.loadTraceDefaultFileName=trace.logTraceFileSize=1024000TraceFileHistory=1TraceFileAppend=No

ALL ALL stderr ALL VERBOSE no


Modifying log files



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.


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.


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.


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.

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.

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.


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.

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 taskYou 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.

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


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.


C h a p t e r 4
4 BMC Impact Integration Web Services Server administration
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69How the BMC II Web Services Server reads selector files and parameters . . . . . . . . 69Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102


Overview

OverviewAdministering 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 instancesThe 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.


Selector file overview

Selector file overviewThe 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.

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.

NOTE The selector file is not required for web service clients that only send events or data or that only launch queries.


Selector file description

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.

Selector file descriptionThe 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:

■ 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.

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.

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.


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 (<)■ less-than or equal to (<=)

The message selector file supports these comparison operators for numerals only.

■ The message selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname=”EVENT”.

■ The message selector file supports required slots. A required slot keyword determines the required slot or slots in the message selector criteria. The message must have the specific required slot for it to match the message selector criteria.


Format

The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you add as a prefix to the specific slot name: for example, reqdslot.msg=”TEXT”. To illustrate, if the message selector criteria specified that the slot msg is required (reqdslot.msg=”TEXT”), then a message that did not have the slot msg would fail the matching test.

The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the message selector criteria.

When the FailOnMissingSlot parameter is set equal to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the message selector criteria.

■ You can use the full range of regular expressions as values for message selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at runtime. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library.

Format

Figure 24 on page 73 depicts the structure of the message selector set file.


Format

Figure 24 Structure of message selector set file

Message selector set files must contain header information that describes the message selector set. The header information consists of

■ message selector set headers, described in “Message selector set header” on page 73

■ message selector headers, described in “Message selector header” on page 74

Message selector criteria are described in “Message selector criteria” on page 76.

Message selector set header

The message selector set header provides the entire set of message selectors in the file with identifying information and indicates whether the message selector set is enabled for use. A single message selector set header must precede all message selectors and their selector groups in the message selector set.

Table 11 on page 74 describes the required and optional message selector set header parameters that precede the message selectors in a set.

Message Selector Set Header

Message Selector Header



Message Selector Criteria




Format

Message selector header

A message selector header

■ provides each set of message selector criteria in the file with identifying information

■ indicates how some message selector features will be implemented■ indicates whether the specific message selector criteria, including any message

selector groups included within it, are enabled for use

Table 11 Message selector set header contents

Parameter Description Inclusion

SelectorSetName= name of the message selector set

Note: The SelectorSetName can be seen in the Trace file. Use this functionality to debug problems with a specific message selector set.

Required

FormatVersion= minimum version of the BMC II Web Services Server required to run the message selector using this file

Optional

Version= version number of the message selector set file, specified manually by the developer or integration end-user

Optional

ChangeDate= date when the file last changed, specified manually by the developer or integration end-user

Optional

Description= free-text description of the entire message selector set

Optional

Enable= specifies whether the message selector set (and all message selectors in it) are enabled for use

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required

Figure 25 Sample message selector set header

SelectorSetName=testselectorFormatVersion=2Version=2.1ChangeDate=August 14, 2005Description=This file contains the event selector testsEnable=TRUE


Format

A message selector header must precede each collection of message selector criteria in the message selector set.

Table 12 on page 75 describes the required and optional message selector header parameters that precede each message selector.

Table 12 Message selector header contents

Parameter Description Inclusion

SelectorName= name of the message selector, used by the BMC II Web Services Server to identify the message selector that will be used in selection

The name must be unique within the message selector set.

Required

Description= free-text description of the message selector Optional

FailOnMissingSlot= indicates whether the match for the message selector fails if a slot specified in the message selector criteria is missing from the message

Valid values:

■ TRUE – the match for the message selector fails if a slot specified in the message selector is missing from the message

■ FALSE – missing slots cause the line to be ignored

If the message that is being examined does not include any of the slots that are being tested by the message selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false.

If you use the reqdslot keyword in the message selector criteria, it is in effect only when FailOnMissingSlot is set equal to false.

Optional

IsSubSelector Indicates whether the message selector can be called only by the $doselector() function. Valid values are true or false.

Optional

Enable= specifies whether the message selector is enabled for use

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required


Format

Message selector criteria

Each message selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in Table 14 on page 80.

Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated).

In addition, the message selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR, ||, or && connector.

Format issues

Messages selector functions, which are internal to the message selector file, are described in Table 13 on page 77. Operators are described in Table 14 on page 80.

■ Each message selector in a set is enclosed in curly braces ({ }).

■ Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep.

■ To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function.

■ Explicit text that is used as a matching criterion must be enclosed in double-quotes (" ").

■ If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match.

■ The message selector functions scan each successive selector group in a message selector until it finds a match. Once they find a match, they stop searching.

■ The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter message selector functions, as well as conceal developer comments. When a line in a message selector is commented out, the selection function ignores it.

Figure 26 Sample message selector set header

SelectorName=EVENT_SELECTORDescription=Selectors for all events of class EVENTFailOnMissingSlot=falseIsSubSelector=trueEnable=TRUE


Format

Do not comment out whole message selectors or selector sets. Instead, set the Enable parameter of the message selector set header or the message selector header to FALSE to disable the message selector set or selector.

EXAMPLE The $functionName resolves a specified function and compares the results of that operation to a slot in the message: for example,

$ClassName = "SECURITY_ALERT"

The $ClassName function returns the class name of the message. The returned value is compared to the value to the right of the operator (in this case, the class name, SECURITY_ALERT). If the message class name is SECURITY_ALERT, then the test is successful.

Table 13 Message selector functions (part 1 of 4)

Function Description

$HostName specifies the host name of the computer on which the message selection program is running: for example, $HostName="MYCOMPUTER".

This function can also be inserted in the new message as a slot value: for example, "MYCOMPUTER"=$HostName.

$ClassName class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event.

Examples:

slot.imclass=$ClassName$ClassName="EVENT"

slot.slotname compares the value of slot.slotname in the message with the value specified to the right of the operator.

When the slot and the value are both present in the message, the criterion is considered a match.

Example: slot.severity = “Critical”


Format

$doselector calls additional message selectors or subselectors, either or both of which can be linked to or included with an overarching message selector

$doselector is used as a single criterion in the message selector or subselector.

$ClassName!="EVENTS"$doselector(security_sel)slot.status != "OPEN"

The message selector examines the message class to determine whether it is “EVENTS.” Then, the message is compared to the security_sel selector. If that comparison is completed successfully (all criteria matching), the comparison process continues processing using the original message selector.

Example of $doselector calling a subselector:

SelectorName=SELECTOR_ONEDescription=does some quick checks then calls the sub selectorFailOnMissingSlot=falseEnable=TRUE{slot.host="bob"$doselector(SELECTOR_SUB)}

SelectorName=SELECTOR_SUBDescription=makes sure it is not a test eventFailOnMissingSlot=falseEnable=TRUE{slot.msg!="This is a test"$Class!="EVENT"}

Note: For a message to be considered a match to a message selector, it must match all the criteria of the message selector, including the criteria of message selectors or subselectors called by the $doselector function.

$slotPresent specifies a slot name that must appear in the message that is being examined for the criterion to be a match

Example: $SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.




Format

$slotMissing specifies a slot name that must not appear in the message that is being examined for the criterion to be a match

Example: $SlotPresent(slot.severity)

Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.

$TimeT returns the number of seconds since January 1, 1970 in number format.

Examples:

mc_date=$TimeTSlot.mc_date=$TimeT

$Format similar to printf, uses %s to insert values into a string, expands \t and \n.

Note: %s is the only formatter available for $format.

Examples:

mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port)$format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin.

$LocalTime enables you to specify the local time using the same format parameters as strftime

Examples:

time=LocalTime("%I:%M:S%p")Slot.time=LocalTime("%I:%M:S%p")

$GmtTime enables you to specify GMT time using the same format as strftime

Examples:

time=$GmtTime("%I:%M:S%p)Slot.time=$GmtTime("%I:%M:S%p")

$subString extracts specified components of a string

Example: msg=$subString(slot.test, 0, 20)

where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.

$ToLower converts all of the characters in a string to lowercase

Example: mc_host=$ToLower(slot.hostname)

$ToUpper converts all of the characters in a string to upper case

Example: mc_domain=$ToUpper(slot.domain)




Format

Table 14 on page 80 describes the operators that can be used for comparison in a message selector set file.

$GetListValue retrieves the value at a specified location in a slot list

Example: note=GetListValue(slot.notes, 3)

where the first parameter (slot.notes in the example) is the slot to be examined from the source message and the second parameter (3) is the index of the value to be retrieved.

$IpFromName performs a domain name server (DNS) lookup for the host name associated with the specified IP address

Example: IP=$IpFromName("hostname.domain")

$HostFromIp performs a DNS lookup for the IP address associated with the specified host name

Example: mc_host=$HostFromIp(slot.srcIP)

Table 14 Message selector operators (part 1 of 3)

Operators Description

= for a match, the result to the left of the equals ( = ) operator must equal the result to the right of the operator

Example: $Slot.Test = “EVENTS”

!= for a match, the result to the left of the not equals ( != ) operator must not equal the result to the right of the operator

Example: $ClassName!="EVENT"

=~ regular expression operator

If the message that is being evaluated by the message selector contains the specified parameter and parameter value, a match is made.

Example: slot.severity=~"MAJ*."

The message selector file supports multiple regular expression operators and keywords.




Format

!=~ regular expression operator

If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails.

Example:

slot.severity!=~"MAJ~."

||OR

symbol and literal string, both of which specify an OR relationship between successive lines of message selector criteria or between successive message selector groups

Example: OR relationship between successive lines of criteria$HostName = “data301”||$HostName = “data400”

By default, AND relationships exist between successive lines of message selector criteria.

&&AND

symbol and literal string, both of which specify an AND relationship between successive lines of message selector criteria or between successive message selector groups

Example: AND relationship between message selector groups

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

By default, AND relationships exist between successive lines of message selector criteria.




Format

Table 15 on page 83 describes message selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name.

{ } indicates groups of alternate message selector criteria within an individual message selector. A group can be nested one level deep.

Example:

{

{slot.Test=”EVENTS”slot.mc_host=”EVENTS”}AND{slot.Test=”EVENTS2”slot.mc_host=”EVENTS2”}

}

> specifies a greater-than comparison. Used exclusively with numerical relationships

Example: slot.Test>10

>= specifies a greater-than or equal to comparison. Used exclusively with numerical relationships

Example: slot.Test>=11

< specifies a less-than comparison. Used exclusively with numerical relationships

Example: slot.Test<12

<= specifies a less-than or equal to comparison. Used exclusively with numerical relationships

Example: slot.Text<=11




Editing the selector file

Editing the selector file

1 If necessary, copy the iiws.selector file from the installDirectory\webServices\conf directory to the working directory of your BMC II Web Services Server installation.

2 In a text editor, open the iiws.selector.

3 Modify the different file components—selector set header, selector header, selector content, and operators—as needed.

4 Save the file using the file name of your choice and the file extension .selector.

5 Ensure that the selector file can be read by the user under whose permissions the web services server is running.



Table 15 Keyword descriptions

Keyword Description

metaslot. designates a slot as a metaslot, which means a slot that provides information about the message. The keyword, followed by a dot, is prefixed to the slot name that it designates.

Example: metaslot.class_name="EVENT"

reqdslot. designates a slot as a required slot. If the FailOnMissingSlot parameter is set equal to FALSE and if the message does not contain the specified required slot, it will not pass the message selector criteria. If the FailOnMissingSlot parameter is set equal to TRUE, then the BMC II C APIs ignore the reqdslot indicator.

Example: reqdslot.msg="TEST"

slot. designates a readable slot value in regular expressions

slot.msg=~"event from slot.host"

The BMC II C APIs return the value of host before forwarding the regular expression to the expression library.



Supplemental message selector files

Supplemental message selector filesThese four supplemental message selector files serve a different filtering purpose for incoming and outgoing events:

■ recvfilterin.selector

■ recvfilterout.selector

■ sendfilterin.selector

■ sendfilterout.selector

On the BMC II Web Services Server side, these supplemental message selector files are stored under the installDirectory\webServices\conf directory. By default, the filters contained in these files are turned off (Enable=FALSE. When you enable them and define the selectors, they are used in conjunction with the iiws.selector file to help filter events in or out.

All incoming and outgoing events that are sent or received by the BMC II Web Services Server are first scanned by the filters in these message selector files. These filters are global, applying to all events that are passed back and forth between the BMC II Web Services Server and the cell. If the incoming events are not rejected by the supplemental message selector files, then they are scanned by the filters in the BMC II Web Services Server’s iiws.selector file, which is specific to the client request.

Table 16 on page 84 describes in more detail the different message selector files.

Table 16 Supplemental message selector files

Direction Message selector file Description

Incoming events

recvfilterin.selector specifies the message selector criteria for accepting incoming events. If the incoming event does not match the message selector criteria, it is rejected automatically.

recvfilterout.selector specifies the message selector criteria for rejecting incoming messages. If the incoming event does not match the message selector criteria, it is passed on to be scanned by the message selector criteria in the integration’s selector file.

Outgoing events

sendfilterin.selector specifies the message selector criteria for approving and passing on outgoing events. If the outgoing event does not match the message selector criteria, it is filtered out automatically.

sendfilterout.selector specifies the message selector criteria for rejecting outgoing events. If the outgoing event does not match the message selector criteria, it is passed to its destination.


Editing the supplemental message selector files

Editing the supplemental message selector files

1 To enable any of the message selector files, open it in a text editor. The example below shows an excerpt from the recvfilterin.selector file:

2 For each selector set and each selector you wish to use, change the Enable parameter from FALSE to TRUE.

You can modify the selector criteria of each selector to accommodate your filtering requirements.

3 Save the modified selector file; do not change the file name.



## Selector Set information SelectorSetName=RECV_FILTER_INVersion=1FormatVersion=2ChangeDate=October 18, 2005Description=This file contains selectors for filtering in incoming eventsEnable=FALSE

SelectorName=BY_CLASSData=Description=This example will filter in based on class.FailOnMissingSlot=falseEnable=FALSE{$ClassName="EVENT"}

TIP Be sure to keep the selector criteria in the supplemental selector files consistent with the selector criteria that is defined in the iiws.selector file. You do not want to accidentally filter out events that your integration client wants to receive.



Configuration file

Configuration fileThe BMC II Web Services configuration file, iiws.conf, is a text file. The configuration file is stored in the installDirectory\webServices\conf directory that resides on the BMC II Web Services Server. It is accessed at runtime by the BMC II Web Services Server.

You can create several configuration files. You decide which one to load on the server to make available to the web service clients.

The configuration file contains parameters that:

■ specify whether the tracing facility is used, where the trace parameters file is located, where the sample log file that is created is located, and how that log file is maintained

■ determine how underlying BMC II C APIs operate

■ are required by your web services server

Configuration file parameters

Table 17 on page 87 lists and describes the configuration file parameters implemented by the BMC APIs.

The default iiws.conf contains a subset of these values, plus unique configuration parameters value.

NOTE

co

It may be convenient for you to store additional parameters required by your web services server in the *.conf file. This is optional.



Table 17 Configuration file parameters (part 1 of 12)

Group Parameter Description

Impact Manager Instances

ServerDirectoryName path and name of the directory file (default file name: mcell.dir). Required.

BMC recommends that you store the mcell.dir file in the integration working directory or in the $MCELL_HOME/etc directory.

Notes:

■ The mcell.dir file contains a list of all BMC Impact Manager instances to which the integration can connect.

■ The integration can use the mcell.dir file supplied with the integration, or it can use the mcell.dir file of a BMC Impact Manager instance that is already installed on the same host.

ServerLocation specifies an individual IP address or host name that the server binds to

Connection Manager

ClientSourceIP static IP address that your integration can use when it is acting as a client (sending events). Optional.

ClientSourcePort port that your integration can use when it is acting as a client (sending events). Optional.

ConnectionSetupTimeOut maximum time, in seconds, that a CLI command attempts to establish a connection to a cell

If the connection with the cell cannot be completely established within this time frame, the command aborts.

Default: 10 seconds

Notes:

■ If the cell is busy with a database cleanup, it may be impossible to connect the CLI with the default values. A database cleanup has a duration limit defined by the EventDBCleanupDurationLimit option, with a default value of 30 seconds. With a default ConnectionSetupTimeOut of 10 seconds, the connection cannot be established within the first 20 seconds of a cleanup.

■ EventDBCleanupDurationLimit is described in the BMC Impact Solutions Infrastructure Administration guide.



Connection Manager (continued)

ConnectionPortRange specifies the range of ports to use for outgoing connections

For a cell, this applies to forward propagation. It is the port used on the client side (or on the propagating cell side). This is useful only to pass the event through firewalls with high restrictions. Most firewall configurations ignore source port information but require destination port information.

However, firewall configuration usually can restrict the source ports as well.

The default is (empty).

ConnectionPortReuse indicates whether or not the ports specified in ConnectionPortRange should be reused as much as possible

By default, the cell or CLI tries to reuse ports from the specified range, in the given order. When ConnectionPortReuse=No, for every new connection within the same session, the next free port from the specified range is used. Only when it reaches the end of the range will it restart at the beginning of the range.

Default=Yes

Encryption indicates whether communications are encrypted

Valid values:

■ No■ Yes (Default)

Message Propagation

MessageBufferKeepSent time, in seconds, to keep sent messages buffered while waiting for an answer

Default: 300 seconds

MessageBufferKeepWait time, in seconds, that messages are retained in the buffer while waiting for the connection to be established

Default: 3600 seconds (one hour)

MessageBufferSize maximum number of messages that can be stored in the message buffer. Optional.

Default: 2000 messages





Message Propagation (continued)

MessageBufferReconnectInterval period of time, in seconds, between attempts to connect to a BMC Impact Manager instance. Optional.

Default: 600 seconds

Notes:

■ The value of this parameter cannot be less than 60 seconds.

■ When a connection is established, the integration sends buffered messages that are designated for the BMC Impact Manager instance with which the connection is established.

MessageBufferResendCount number of times to resend unanswered messages

Default: 1





Persistency Buffer Manager

PersistencyEnabled enables persistency, which specifies additional buffering parameters when the buffer mode is Default

Valid values:

■ No (Default)■ Yes

PersistencyLevel buffer mode used when the Default buffering mode is specified. This parameter is enabled only when the PersistencyEnabled parameter value is Yes. Optional.

Valid values:

■ None (Default)■ Low ■ High

Note: These values are case-sensitive and should be entered as shown here.

PersistencyFileName name of the file in which the buffered messages are stored

Default: log_directory\imgw-integrationName.dat [persist.dat]

PersistencyCleanupSizeThreshold

threshold size, in bytes, of the persistency file that activates garbage collection

PersistencyCleanupGarbageThreshold

threshold size, as a percentage of file size, of the persistency file that activates garbage collection

The default is 40 percent.

PersistencyDisconnectRemovesMessages

indicates whether messages written to the persistency file are deleted when the integration disconnects intentionally from a BMC Impact Manager instance

Valid values:

■ No (Default value)■ Yes

Note: The contents of the file are not deleted when the integration terminates unexpectedly.





Heartbeats HeartBeatInterval integer that indicates the number of seconds between heartbeats.

Default value: 30 seconds

The minimum value is 1 second. The configuration file does not define a maximum value.

EnableHeartBeats a Boolean indicator that determines whether the integration component uses the heartbeat signal. Valid values are

■ true/false■ yes/no

The entries are not case sensitive.

Receive buffer KeepRecvPersisted Boolean indicator that determines whether a message file persists when the associated message is removed from the message queue

Valid values are


The entries are not case sensitive. The default value is true or yes, indicating that the persistent file that contains a copy of the message remains after the message is removed from the queue.

When the integration is running in server mode and receives an incoming message (an event or a modify), it saves a copy of the message to a file. By default, the integration does not delete the message file until the integration calls the bmcii_freeMessage() function. If you set the KeepRecvPersisted parameter value to false or no, the integration deletes the message file when the message is removed from the queue.

ReceiveBufferDir the directory where receive buffer resides. The default is the log_directory

EnableRecvPersist Boolean indicator that shows whether the message file persists in the incoming buffer. The default is false, meaning that the message file is not persisted in the incoming buffer.





Receive buffer(continued)

DropAcks Boolean indicator (true/false, yes/no) that tells the receive buffer to retain or drop acknowledgments. The default is true. When the DropAcks is set to true, the integration application does not receive replies indicating that the request is a success. However, the integration application still receives cancellation notices and error messages.

Do not modify the default setting because the BMC II Web Services Server does not need to process acknowledgments. It operates more efficiently by not processing them.

RecvBufferSize number value that restricts the number of

■ events■ acknowledgements■ error messages■ cancellation notifications■ status notifications■ connection notifications

that are stored in their respective buffers and that are received from a cell (propagation), an mposter command, or another integration.

Note: These items are stored in two separate buffers. The RecvBufferSize value applies to each one. Events and modifies are stored in one buffer, while the acknowledgements, error messages, and notifications are stored in a second buffer.

The default value is 20,000. When the default or specified maximum value is reached in each buffer, the buffer discards the oldest item and begins to cycle the items as new ones are received. If you set the value to 0, then no restriction is placed on the size of either buffer.





Trace Parameters Trace flag that indicates whether tracing is enabled. Optional.

Valid values:

YES or ON– enable tracing

NO or OFF – disable tracing (Default)

TraceSrc when displaying a trace message, specifies whether to display the source code file name and line number where trace message originated. Optional.

Valid values:

YES or ON – display file name and line number

NO or OFF – no display of file name and line number

Note: Depending on the location of the trace message, the source may be in the integration or the BMC II Web Services Server code.

TraceTime Boolean indicator that says whether the date and time are appended to the trace file. The default value is YES. Valid values are

YES or ON – date and time are appended to the trace value

NO or OFF – date and time are not appended

TraceConfigFileName path and file name for the iiws.trace file. Required, if Trace=YES.

You can enter a hard-coded file path or use the substitution parameters described in “Editing the configuration file” on page 98.

TraceDefaultFileName default destination file (trace.log) to which trace messages are redirected from stderr, when the integration runs as a daemon or a service. Required, if Trace=YES.





Trace Parameters (continued)

TraceFileSize maximum size, in KB, of the trace messages file. Optional.

Valid values:

0 - No limit

n - size of file in KB

Note: BMC recommends that the value of this parameter be no less than 500 KB.

TraceFileHistory number of trace files to be kept in history. Each file numbered sequentially. Optional.

Valid values:

0 – No files kept. (Default)

n - number of files to keep

TraceFileAppend when the integration is restarted, specifies whether to append new trace messages to the existing message trace file. Optional.

Valid values:

YES or ON – appends new messages to the existing trace message file (Default)

NO or OFF - empties the current trace message file





Troubleshooting UseMemWatch Boolean indicator that activates a debug behaviors which determines whether the integration is passing bad data to the BMC II C APIs

Valid values are


The default value is false or no.

If you enable the UseMemWatch parameter, the BMC II C APIs maintain a list of valid memory that contains strings, string lists, messages, and replies. Any memory objects that the BMC II C APIs create and pass back to the integration are tracked and verified.

You can view any errors in the integration’s trace log.

The memory list created by the BMC II C APIs does not validate string values that are created by an integration.

DumpIncoming Boolean indicator that tells the integration whether to add incoming events to the trace file. The default is false.

Performance MinClientSleep For an integration that is defined as a client, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows■ 1 to 2000 milliseconds on UNIX platforms

The default value is ten milliseconds on both platforms.

Note: If your client sends a large number of events in a continuous stream, you can consider increasing the MinClientSleep value so that the client can use more time to send events and the BMC IM cell can keep pace with the event processing.





Performance(continued)

MinSleep For an integration that is in server mode, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing.

The valid values are

■ 0 to 2000 milliseconds under Windows; default value is 0

■ 1 to 2000 milliseconds on UNIX platforms; default value is 1

MaxSleep string value that determines the upper range of the receive thread’s pause time

The valid values range from any value greater than the MinClientSleep or MinSleep value to 2000 milliseconds. The default value is 500 milliseconds.

MinQueryTimeout integer that specifies the absolute minimum time in milliseconds that the integration waits for a query result before it times out. The timeout period measures the time between responses from the cell. The default value is 2000 milliseconds (2 seconds).

For example, your query call requests 100 results. You receive the first 50 results without a delay equal to or greater than 2 seconds. However, you do not receive the next result within two seconds. Your integration then times out.

You can override this configuration parameter value in the query function bmcii_retrieveQueryResults by specifying a timeout value greater than the minimum specified by the MinQueryTimeout parameter. If the value is the same or lower, it is ignored.





Miscellaneous

UniqueIDFile overrides the default name and/or location of the uniqueID.dat file. Optional.

Notes:

■ The default location is the workingDir/log/instance_name/uniqueID.dat. The location and name of this file can be overridden.

■ To use this parameter, the integration must have permission to write to the uniqueID.dat file.

■ The value of this parameter in this file increments by one (1) before a new ID is assigned.

ServerAllInterfaces specifies whether a newly-created server binds to all available interfaces. Optional.

Valid values:

■ YES or ON – binds (Default)■ NO or OFF – does not bind

You use this parameter whenever you run the BMC II C APIs as a service. When running a as service, you bind to a specific port number where you receive all network traffic. If you have multiple Ethernet cards, you can say you want to bind to the same port on all of the Ethernet cards (interfaces). Alternatively, you can bind to a specific interface by binding to an IP address.

Note: For more information about binding and the ServerAllInterfaces cell configuration parameter, see the BMC Impact Solutions Infrastructure Administration guide.

LocaleConfigFileName directory path for language support where the catalog files and the .load file are located. The default is under the ./locale path: for example, IMPACT_SOLUTIONS_HOME/webServices/IIWS/locale/iiws.load.

BMC II Web Server specific parameters

DisableSlotListSet always equal to Yes

This configuration parameter value enables the BMC II Web Services Server to process incoming messages that are enclosed within brackets as regular slot strings.




Editing the configuration file

Editing the configuration file

1 If necessary, copy the iiws.conf file from the installDirectory\webServices\conf directory to the corresponding location of your web service server installation.

2 Using a text editor, open the iiws.conf file.

3 Modify the values of the required parameters and any optional parameters that you want to include (described in Table 17 on page 87).

BMC II Web Server specific parameters(cont)

MessageListenerCellName name of the message listener cell that the BMC II Web Services Server uses to receive requests

The default name is WSCELL. Whatever name you choose, you must specify the exact name in all instances of its use in the applicable configuration files.

MaxReturnEventListSize contains an absolute value of type int

It defines the maximum number of events that the server returns per polling request. This value can be different from the number of events that the client requests. The recommended range of values is 20 to 100. The default is 20.

IIAPISelectorFile name of the event selector file that BMC II Web Services Server uses

The default name is iiws.selector.

ServerCacheDir name of the cache directory for the BMC II Web Services Server

The default name is cache.




Trace file

4 Optional. Modify the file to include any optional BMC II Web Services Server parameters that you want to use. Table 17 on page 87 lists these parameters.

5 Optional. Add any integration-specific configuration parameters (not directly related to BMC II Web Services) that you want to store with the BMC Impact Manager configuration data.

6 Save the file using the file name of your choice and the file extension .conf.

7 Ensure that the configuration file can be read by the user under whose permissions the web services server is running.

8 If you overrode the default location or name of the UniqueID.dat file, described in Table 17 on page 87, you must grant the web services server write access on the file.



Trace fileA sample iiws.trace file is located under installDirectory\webServices\conf. By default, the trace functionality is enabled.

The BMC II Web Services Server writes its logging messages to the iiws.trace file.

NOTE You can use the following substitution parameters in the configuration (.conf) and trace (.trace) files:

%H – home directory%C – configuration directory%L – log file directory%T – temporary file directory%P – Integration name%N – Instance name

For more information about path value variables, see the BMC Impact Solutions Infrastructure Administration guide.



Editing the trace configuration file

Configure trace functionality as you would in a BMC Impact Manager product instance.

To set up tracing, you must modify:

■ the trace parameters in the iiws.conf file. For more information, see “Editing the configuration file” on page 98.

■ the trace configuration file. See “Editing the trace configuration file” on page 100.

For more information about the configuration files (*.conf and *.trace), see the BMC Impact Solutions Infrastructure Administration guide.

Figure 27 on page 100 depicts a sample trace file.

Editing the trace configuration file

1 If necessary, copy the iiws.trace file from the installDirectory\webServices\conf to the working directory of your BMC II Web Services Server installation.

2 In a text editor, open the iiws.trace.

3 Modify the file according to the instructions in the BMC Impact Solutions Infrastructure Administration guide.

Figure 27 Sample trace configuration file

# BMC Impact Manager 3.2 # Cell trace configuration file # # Configuration: # This configuration mentions the destination for trace messages # on a module/level basis. It can also indicate destinations for # special tracing switches. # Each configuration line overrides any possible previous settings. # # Format of a configuration line: # Module Level Destination # Module SWITCH Switch Destination # Where # Module = name of module (see list 'Module' below) # Level = message level (see list 'Level' below) # Switch = switch name (see list 'Module Switch' below) # Destination = destination file name or predefined value # (see list 'Destination' below) # A wildcard can be specified for Module and for Level : # ALL or *

ALL ALL stderr ALL VERBOSE no


mcell.dir file

4 Save the file using the integrationName.trace naming convention.

5 Grant the integration account read access to the integrationName.trace file.

6 Ensure that the TraceConfigFileName parameter in the iiws.conf file points to the location in which you saved the integrationName.trace file.

7 Save the file using the file name of your choice and the file extension .trace.

8 Ensure that the trace file can be read by the user under whose permissions the BMC II Web Services Server is running.

9 Important. Ensure that the TraceConfigFileName parameter in the .conf file points to the location in which you saved the .trace file.



mcell.dir fileThe mcell.dir file lists the identifying information for all BMC Impact Manager product instances (cells) and event receivers (WSCELL) to which your implementation can connect and communicate. It is used to look up a BMC Impact Manager product instance or web services server name and to determine its host, port, and encryption key.

NOTE You can use the following substitution parameters in the .trace file.:

%H – home directory%C – configuration directory%L – Integration log file directory%T – Integration temporary file directory%P – Integration name%N – Instance name

For more information about path value variables, see the BMC Impact Solutions Infrastructure Administration guide.



Editing the Integration mcell.dir file

Editing the Integration mcell.dir file

See “Synchronizing BMC II Web Services Server and BMC IM cell connections” on page 38 for the procedure for editing the respective mcell.dir files of the BMC Impact Manager instance and of the BMC II Web Services Server installation.

TIP In the configuration file, ensure that the ServerDirectoryName parameter points to the directory location of the mcell.dir file on the BMC II Web Services Server.


A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index

Symbols$ClassName function 77$doselector function, description 78$Format function 79$function_name function 77$GmtTime function 79$HostName function 77$LocalTime function 79$slotMissing function 79$slotPresent function 78$TimeT function 79%C substitution parameter 99, 101%H substitution parameter 99, 101%L substitution parameter 99, 101%MCELL_HOME% 39%N path value variable 99, 101%P substitution parameter 99, 101%s 79%T substitution parameter 99, 101

Aadministration

BMC Impact Integration Web Services Server 68, 69editing iiws.conf file 98editing iiws.selector 83editing iiws.trace file 100iiws.conf file 86iiws.selector file 69iiws.trace file 99starting BMC Impact Integration Web Services Server

34audience

presumed knowledge 18roles 18

BBMC Atrium Core 12, 21, 22

download 22BMC Impact Integration Web Services Server

adminstration 69components 12guaranteed event delivery 17installation package 20

mcell.dir 14queries 16receiving events 17required configuration tasks 38selector processing 69send request 16SOAP messaging 14starting 34subscription requests 17

BMC Performance Manager 12, 56BMC Software, contacting 2bmcii_loadSelectorSet function, failure 70buffering

buffer, maximum size 88MessageBufferReconnectInterval parameter 89MessageBufferSize parameter 88reconnect interval 89

CC API runtime libraries 14cache directory 24ChangeDate parameter, message selector set header 74class definition queries 16classes, specifying in translation maps 77ClientSourceIP configuration parameter 87ClientSourcePort configuration parameter 87configuration

.iiws.conf file 86

.load file 50

.mrl file 50BMC Impact Integration Web Services Server 38defining propagate rules 49HTTP transport server 58mcell.dir 38

configuration file (iiws.conf file)editing 86, 98overview 86substitution parameters 99

configuration filesparameters 87substitution parameters 101TraceConfigFileName parameter 93

configuringconfiguration file parameters 87

Index 103


iiws.conf 87Trace parameter 93TraceConfigFileName parameter 93TraceDefaultFileName parameter 93TraceFileAppend parameter 94TraceFileHistory parameter 94TraceFileSize parameter 94TraceSrc parameter 93

connecting, maximum reconnect interval 89ConnectionPortRange configuration parameter 88ConnectionPortReuse configuration parameter 88ConnectionSetupTimeOut configuration parameter 87customer support 2

DDescription parameter

in message selector header 75in message selector set header 74

Eembedding message selectors 71Enable parameter

in message selector header 75in message selector set header 74

encryptionEncryption parameter 88

Encryption configuration parameter 88event propagation

defining rules in KB 45example rule 48Propagate policy 44subscription requests 17WSCELL event listener 17, 44, 46

FFailOnMissingSlot message selector header parameter 75failure

matching 75selection 75

formatting%, using in message selectors 79message selectors and message selector sets 73

FormatVersion parameter, in message selector set header 74

functions$ClassName 77$doselector 78$Format 79$function_name 77$GmtTime 79$HostName 77$LocalTime 79

104 BMC Impact Integration Web Services Server Insta

$slotMissing 79$slotPresent 78$TimeT 79in message selectors 76slot.slotname 77

Gguaranteed event delivery 17

Hhigh availability cells

configuration 53configuration with BMC Performance Manager 56guidelines 55implementation scenarios 53

host names, specifying in message selectors 77HSQLDB database server 51

Iiiws.conf file, editing 98iiws.conf, configuration parameters 87iiws.selector file 83iiws.trace file 100iiws_node CLI 37iiws_node node 26Impact Integration C APIs

relation to Web services 14runtime libraries 14

ImpactManagerService service assembly 26installation

compatible cells 21compatible toolkits

toolkitsVisual C#.NET 2003 21

directory contents 24log files 25procedure 22supported operating systems 20verifying web related processes 26

Llocale directory 25localization, LocaleConfigFile 97

Mmcell.dir

adding WSCELL event listener 42configuration 38

llation and Configuration Guide


description 14, 101directory location 25editing 101location 15WSCELL event listener 15

message buffer capacity 88message propagation

MessageBufferKeepSent parameter 88MessageBufferKeepWait parameter 88MessageBufferReconnectInterval parameter 89MessageBufferResendCount parameter 89MessageBufferSize parameter 88parameters list 88

message selectorscharacteristics 70content 76embedding 78embedding with $doselector 71file, characteristics 70formatting 73header requirement 75header sample 76message selector set header 73name 75operators 80parameters, header 75parameters, set header 74set header requirement 73set header sample 74sets, description 70sets, formatting 73sets, headers 73sets, naming 70slots, missing 75syntax rules 70time, specifying settings 79

MessageBufferKeepSent 88MessageBufferKeepSent configuration parameter 88MessageBufferKeepWait configuration parameter 88MessageBufferReconnectInterval configuration parameter

description 89MessageBufferResendCount configuration parameter 89MessageBufferSize configuration parameter

description 88

Nnon-reliable subscription 18

Pparameters

ChangeDate 74ClientSourceIP 87ClientSourcePort 87

configuration file 87ConnectionPortRange 88ConnectionPortReuse 88ConnectionSetupTimeOut 87Description 74DropAcks 92DumpIncoming 95Enable 74, 75EnableRecvPersist 91Encryption 88FailOnMissingSlot 75FormatVersion 74KeepRecvPersisted 91LocaleConfigFile 97MaxSleep 96message selector set header list 74MessageBufferKeepWait 88MessageBufferReconnectInterval 89MessageBufferResendCount 89MessageBufferSize 88MinClientSleep 95MinSleep 96PersistencyCleanupGarbageThreshold 90PersistencyCleanupSizeThreshold 90PersistencyDisconnectRemoveMessages 90PersistencyEnabled 90PersistencyFileName 90PersistencyLevel 90ReceiveBufferDir 91SelectorHeader 75SelectorSetName 74ServerAllInterfaces 97ServerDirectoryName 87substitution parameters 101TraceConfigFileName 93TraceDefaultFileName 93TraceFileAppend 94TraceFileHistory 94TraceFileSize 94TraceSrc 93UniqueIdFile 97UseMemWatch 95Version 74

PersistencyCleanupGarbageThreshold configuration parameter 90

PersistencyCleanupSizeThreshold configuration parameter 90

PersistencyDisconnectRemoveMessages configuration parameter 90

PersistencyEnabled configuration parameter 90PersistencyFileName configuration parameters 90PersistencyLevel configuration parameter

description 90polling interface 17ports

changing 60Web services server 16

Index 105


WSCELL event listener 15printf function 79product support 2Propagate policy 44propagate. See event propagation

Qqueries

class definition 16description 16processing 16service model 16

SSelectorName message selector header parameter 75selectors

iiws.selector file 83in subscription requests 70overview 69

selectorset_name.message selector file 70SelectorSetName message selector set header parameter 74send request processing 16ServerAllInterfaces configuration parameter 97ServerDirectoryName configuration parameter 87service model queries 16slot.slotname function 77slots

in message selectors 76missing from message selectors 75selecting, by value 77

SOAP messaging 14strftime 79substitution parameters 101support, customer 2

Ttechnical support 2TIBCO platform 12

ActiveMatrix Administrator console URL address 13assumed knowledge 18default HTTP server port 13documentation 25installation options 22logging configurations 62manually starting processes 51stack disk requirements 22substitution variables 18

time, using in message selectors 79time_t, in message selector files 79toolkits

Axis 21Composite Information Server 21

106 BMC Impact Integration Web Services Server Insta

stub generation 14Trace parameter 93TraceConfigFileName configuration parameter 93TraceConfigFileName parameter 93TraceDefaultFileName configuration parameter 93TraceFileAppend configuration parameter 94TraceFileHistory configuration parameter 94TraceFileSize configuration parameter 94TraceSrc configuration parameter 93TraceSrc parameter 93tracing

parameters in BMC II C APIs configuration files 93TraceConfigFileName parameter 93TraceDefaultFileName parameter 93TraceFileAppend parameter 94TraceFileHistory parameter 94TraceFileSize parameter 94TraceSrc parameter 93

translationclass names, specifying 77host names, specifying 77

UuniqueID.dat 97UniqueIdFile configuration parameter 97using substitution parameters 101

VVersion, message selector set header parameter 74

WWeb service client

compatible toolkits 14interface types 17polling interface 17queries 16

WSCELL event listeneradding to mcell.dir 42description 15event propagation 44, 46port 15

llation and Configuration Guide

Notes

*103303**103303**103303**103303*

*103303*

Documents

BMC Impact Integration Web Services Server Installation ...atmgmicrosoft.free.fr/depot/at/BMC doc/BMC Impact Integration Web... · Starting TIBCO-related web services processes