BMC Impact Integration Developer's Kit Web Services Server ...

BMC Impact Integration Developer’s Kit Web Services Server Developer Guide

Supporting BMC Impact Integration Developer’s Kit v. 7.1 BMC Impact Integration Web Services Server v. 7.1

January 2008

www.bmc.com

Contacting BMC Software You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.

United States and Canada Address

BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA

Telephone

713 918 8800 or 800 841 2031

Fax

(01) 713 918 8000

Fax

713 918 8000

Outside United States and Canada Telephone

(01) 713 918 8800

© Copyright 2003–2008 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. IBM and AIX are registered trademarks of International Business Machines Corporation. Linux is the registered trademark of Linus Torvalds. Java, Sun, JRE, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and several other countries. UNIX is a registered trademark of The Open Group. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.

Restricted rights legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.

Customer support You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see “Before contacting BMC.”

Support website You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can ■ ■ ■ ■ ■ ■ ■ ■

read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation download products and maintenance report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers

Support by telephone or e-mail In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to [email protected]. (In the subject line, enter SupID:, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC Have the following information available so that Customer Support can begin working on your issue immediately: ■

product information — — —

■

product name product version (release number) license number and password (trial or permanent)

operating system and environment information — — — — —

machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level

■

sequence of events leading to the issue

■

commands and options that you used

■

messages received (and the time and date that you received them) — — —

product error messages messages from the operating system, such as file system full messages from related software

3

License key and password information If you have questions about your license key or password, contact BMC as follows: ■

(USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail message to [email protected].

■

(Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an e-mail message to [email protected].

■

(Asia-Pacific) Contact your BMC sales representative or your local BMC office.

4


Contents Chapter 1

Introduction

13

BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features available to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible programming languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended audience for web services APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14 14 16 16 16 17 17 18 18 18 18 19 19

Chapter 2

21

Installation

Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible web services toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenSSL compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting environment variables under Microsoft Windows . . . . . . . . . . . . . . . . . . . Setting environment variables under Solaris, Linux, HP-UX, and AIX . . . . . . . . Uninstalling the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

22 22 22 23 23 23 24 24 29 31 31 32 34

Chapter 3

37

Configuration

Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 How to synchronize BMC II Web Services Server and BMC IM cell connections. . 38 Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 44 Defining Propagate rules or event propagation policies for BMC IM cells . . . . . 45 Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Configuring high availability cells for the BMC II Web Services Server . . . . . . . 51 Contents

5

Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Configuring Attributes in the BMC II Web Services Server . . . . . . . . . . . . . . . . . . 57 Modifying the default BMC II Web Services Server log . . . . . . . . . . . . . . . . . . . . . 58 Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 59 Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Installing multiple instances of the BMC II Web Services Server . . . . . . . . . . . . . . . . . 62 When to assign a unique server instance name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Administering the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Chapter 4

Securing web services

65

Secure Sockets Layer (SSL) security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Security implementation advisory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Compatible OpenSSL toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Guidelines for implementing SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Obtaining the OpenSSL source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 About certificate generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Generating the BMC II Web Services Server certificate (Microsoft Windows). . . 68 Generating the BMC II Web Services server certificate (UNIX or Linux) . . . . . . . 69 Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Chapter 5

Guidelines for choosing client interfaces

73

Client components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Programming language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Available web services client features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Guidelines for building a client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Preparing the WSDL source-code generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Generating the client proxy code (client stubs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Systinet WASP Server for C ++ toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 .NET C# toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Apache Axis toolkit sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Using the NO_INOUT operations to return single elements for the Axis toolkit 78 Deciding which stub operations to use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Compiling the client code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Maximum number of open outgoing connections . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Implementing the send feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 How a send request is processed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Implementing the query features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 How a query is processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Sequence of operations to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 bmciiws_queryClassDefinitions: class definition array . . . . . . . . . . . . . . . . . . . . . . 86 Implementing the receive feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Selector choices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 6


Polling interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Publish-subscribe interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Reliable versus non-reliable subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Polling client (non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Polling client (reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Listener client (reliable or non-reliable subscription) . . . . . . . . . . . . . . . . . . . . . . . 95 Using multiple subscription calls (bmciiws_subscribe_reliable) . . . . . . . . . . . . . . 96 Registering and receiving service component state change events . . . . . . . . . . . . 98 Workaround: multiple clients and state change events. . . . . . . . . . . . . . . . . . . . . . 99 Implementing the Secure WASPC client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Appendix A

BMC Impact Integration Web Services Server Administration

105

Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the BMC II Web Services Server reads selector files and parameters . . . . . . . Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

106 106 106 107 107 109 120 121 122 123 123 136 137 138 139 139

Appendix B

141

Error Messages and Codes

BMC II Web Services Server error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II C APIs and core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Errors listed By error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core communications errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Errors listed by error code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

141 144 144 146 157 157 158

Appendix C

163

Sample Client Files

List of sample client files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Listener Web Services Description Language (WSDL) file . . . . . . . . . . . . . . . Event listener server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

163 165 166 166 166 167 167 168

7

Bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Listenercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Adding SSL parameters to the listenercfg.xml file . . . . . . . . . . . . . . . . . . . . . . . . . 173

8

Index

175

Glossary

183


Figures Components of BMC Impact Integration Web Services . . . . . . . . . . . . . . . . . . . . . . . . 15 mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 mcell.dir example: BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 mcell.dir example: BMC IM cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Event propagation: many instances to one server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Event propagation: many instances to many servers . . . . . . . . . . . . . . . . . . . . . . . . . . 47 HA implementation scenario: primary cell server and web server on same system 52 HA implementation scenario: primary cell server and web server on different systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 HA implementation scenario for BPM and BMC II Web Services Server . . . . . . . . . 55 servercfg.xml file: default declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Servercfg.xml with openSSL parameters added and transport section removed . . . 71 Runtime directory folders for stub files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 bmciiws_queryClassDefinitions code sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Class definition array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Sample trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Dispatch Operations in EventListener.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Figures

9

10


Tables Wasp library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Tested compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Compatible toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 UNIX distribution files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Location of mcell.dir Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 mcell.dir configurations for queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 mcell.dir configurations for sending events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 mcell.dir configurations for receiving events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Default port numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Summary of Available Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Components that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Event selectors for subscription requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 SIM_NOTIFICATION_REGISTRY message class: required slots . . . . . . . . . . . . . . . . 99 Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 BMC II C APIs Impact Integration Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Core Communications Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Sample client files: Systinet C++ queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Sample client files: Systinet C++ listener client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Sample client files: Axis Java implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Namespaces: EventListener.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Message Parts: Dispatch_Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Message Parts: DispatchList_Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Tables

11

12


Chapter

1

1

Introduction This chapter introduces the BMC Impact Integration Developer’s Kit and the BMC Impact Integration Web Services Server APIs. It describes the following topics: BMC Impact Integration Developer’s Kit overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview to BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . BMC Impact Integration Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II C APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL file and SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolkits and client-side interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features available to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible programming languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features of the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSCELL event listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended audience for web services APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1

Introduction

14 14 16 16 16 17 17 18 18 18 18 19 19

13

BMC Impact Integration Developer’s Kit overview

BMC Impact Integration Developer’s Kit overview The BMC Impact Integration Developer’s Kit (BMC II Developer’s Kit) enables developers to build applications that can integrate with BMC Impact Manager events and data. The BMC II Developer’s Kit includes: ■

■

BMC Impact Integration C APIs—a toolkit that provides functions to interact with the BMC Impact Manager product and its components. This API can be used in C or C++ environments. These APIs offer developers the ability to quickly integrate and set up the bidirectional flow of events and data between their applications and the BMC Impact Manager product. BMC II Web Services APIs—a toolkit that exposes an open-standards web services interface with which to implement loosely coupled BMC Impact Manager integrations, to build client applications that utilize BMC Impact Manager data, and to remotely access an BMC Impact Manager network through standard Web protocols. The web services interface is defined through the Web Services Description Language that serves as the contract between the web service and the client application.

These APIs offer developers the ability to quickly build integrations that share events and data with the BMC Impact Manager product or to display BMC Impact Integration information in Web-based applications.

NOTE The BMC Impact Integration Developer’s Kit does not include the BMC Impact Manager product. You must purchase this product separately or have it already installed.

Overview to BMC Impact Integration Web Services Server The BMC Impact Integration (BMC II) Web Services Server APIs enable you, as a web services developer, to build a platform-independent web services client that exchanges events and data with a BMC Impact Manager instance.

14


Overview to BMC Impact Integration Web Services Server

NOTE The BMC Impact Integration Web Services Server APIs contains a pre-built web service. The web services developer is responsible for building the client.

Your 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 BMC Impact Integration Web Services

The BMC Impact Integration Web Services Server package includes ■

XML to describe message content

■

Web Services Description Language (WSDL), an XML document that defines the data types, messages, operations, and binding protocol of this web service

■

Simple Object Access Protocol (SOAP) over HTTP as a transport mechanism between Impact Integration Web Services Server and Impact Integration Web Services client

■

a web services server that can process callbacks and forward events to subscribing clients through an event dispatcher

■

sample client code

NOTE The BMC II Web Services Server does not include a Universal Description Discovery, and Integration (UDDI) registry.

Chapter 1

Introduction

15

BMC Impact Integration Web Services Server

BMC Impact Integration Web Services Server NOTE The current release of BMC II Web Services does not support the porting of the BMC II Web Services Server to other web servers.

The BMC II Web Services Server is already programmed to exchange event information between your web service client and BMC Impact Manager cells. The BMC II Web Services Server also supports listener libraries. This component enables a client to receive BMC Impact Manager events through callbacks. The BMC II Web Services Server contains the Wasp library file of the Systinet™ WASP server. Table 1 lists the names and extensions of the library file in the different operating systems. Table 1

Wasp library files

Operating system

Name of Wasp library file

Microsoft Windows

waspc.dll

Solaris™ and Linux®

libwasp.so.4

HP-UNIX

libwasp.sl

AIX®

libwasp.a

BMC II C APIs The BMC II Web Services Server contains the runtime libraries of the BMC II C APIs.

WSDL file and SOAP messages The BMC II Web Services Server package includes a static, read-only Web Service Descriptive Language file (.wsdl) called ImpactManager.wsdl. The ImpactManager.wsdl file is in XML format. It points to three schema definition files:

16

■

Event.xsd

■

BasicTypes.xsd

■

ImapiTypes.xsd


Toolkits and client-side interfaces

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for a detailed description of the WSDL and schema definition files.

The BMC II Web Services Server exposes its APIs through its ImpactManager.wsdl file. It uses the document/literal style of SOAP messaging format to communicate with client programs.

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

Toolkits and client-side interfaces To create a web service client, BMC recommends that you choose from among the compatible toolkits (see “Compatible web services toolkits” on page 23). 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 Systinet libraries can understand and processes it accordingly.

Features available to clients The BMC II Web Services Server APIs enable you to implement clients that use one or more of the following features: ■ ■ ■ ■

sends events and data queries for events, data, class definitions, and service model information receives events through subscription requests and callbacks receives events through subscription requests and polling calls

The APIs let you customize your queries and subscription requests so that, for example, you can specify which data you want to retrieve and which events to receive.

Chapter 1

Introduction

17

Compatible programming languages

Compatible programming languages You can build a client using the C++, C# , or Java programming language.

Features of the BMC II Web Services Server This section describes the BMC II Web Services Server’s unique requirement for the mcell.dir file, and it summarizes the different ways in which the BMC II Web Services Server handles client interfaces.

mcell.dir After you install the BMC II Web Services Server, an mcell.dir file is generated with two default entries. In addition to the local cell entry, which most BMC Impact Manager users are familiar with, it also includes an entry for the event listener component called WSCELL. The following example shows the entries with the default port numbers. cell cell

local WSCELL

mc mc

localhost:1828 127.0.0.1:19999

In the standalone BMC II Web Services Server installation, the mcell.dir file is installed under the drive:\installDirectory\mcell or installDirectory/mcell 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 the mcell.dir file of each sending cell. (See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information.) 18


Support overview

Support overview You request the BMC Impact Integration Developer’s Kit through the BMC Developer Network website at http://developer.bmc.com. To obtain general support information, such as finding out how to extend the tools in the kit and develop integration applications, you can go to the BMC Developer Connection. It provides developers with moderated peer support and offers a free, supportive Web site where you can get answers to your questions about developing integrations with the BMC Impact Manager product. For more information on joining, go to the BMC Developer Connection Web site at: http://devcon.bmc.com/.

NOTE At the time of publication, BMC intends to eventually migrate the content of the BMC Developer Connection website to the BMC Developer Network website at http://developer.bmc.com.

If you have found a bug in the toolkit or an error in the documentation, please report it to BMC Customer Support. (See the Customer Support contact information in the front matter of this guide just after the title page.)

Intended audience for web services APIs The audience of the web services APIs is experienced developers who are knowledgeable about web services technologies: XML; Simple Object Access Protocol (SOAP); Web Services Description Language (WSDL); and Universal Description and Discovery Interface (UDDI). The web services audience should be acquainted with BMC Impact Manager, but it does not need to be as familiar with the BMC Impact Manager product as does the C developer audience. The web services audience should have experience in ■ ■ ■ ■

writing code in one or more programming languages building client applications for web services interfaces working with client proxy code (client stubs) generating secure sockets layer (SSL) certificate requests

The audience of the web services APIs also includes 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. It would be helpful if the administrator were also familiar with web services.

Chapter 1

Introduction

19

Intended audience for web services APIs

20


Chapter

2

2

Installation This chapter presents the following topics: Installation package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported operating systems and other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC IM support matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatible web services toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OpenSSL compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation directory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Post-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting environment variables under Microsoft Windows . . . . . . . . . . . . . . . . . . . Setting environment variables under Solaris, Linux, HP-UX, and AIX . . . . . . . . Uninstalling the web services server package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2

Installation

22 22 22 23 23 23 24 24 29 31 31 32 34

21

Installation package contents

Installation package contents The BMC II Web Services Server package consists of the following components: ■ ■ ■

■ ■

server binaries and server executable 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 sample client code

Supported operating systems and other resources Table 2 lists the operating systems that are compatible with this release: Table 2

Supported operating systems

Operating system

Version or Service pack

Windows 2003 Server, 32-bit

SP1

Red Hat Enterprise Linux Advanced Server (Intel, 32-bit) 3.0, 4.0 SUSE Linux Enterprise Server (Intel, 32-bit)

9.0, 10.0

Sun™ Solaris (SPARC)

9, 10

IBM® AIX (POWER)

5.2, 5.3

HP-UX (PA-RISC)

11i, v1, v2

BMC IM support matrix Table 3 lists the versions and features of BMC Impact Manager (BMC IM) that the BMC II Web Services Server supports. Versions 5.1 and later provide language support for Simplified Chinese, Traditional Chinese, Korean, and Japanese languages. Table 3

BMC IM support matrix (part 1 of 2)

BMC IM version

Event and data exchange

Service model queries

Language support

5.1

Yes

Yes

Yes

5.1.01

Yes

Yes

Yes

22


Compilers

Table 3

BMC IM support matrix (part 2 of 2)

BMC IM version

Event and data exchange

Service model queries

Language support

7.0.x

Yes

Yes

Yes

7.1

Yes

Yes

Yes

Compilers You are free to choose your own compiler to build your client. Refer to the following table for a list of compilers that the client sample code has been tested against. Table 4

Tested compilers

Platform

Compiler

Microsoft Windows

Microsoft Visual Studio, version 6.0

Linux

GNU Complier Collection (GCC) 2.96

Solaris

SPARCWorks CC 5.0

HP-UX

HP aCC 3.3x

Compatible web services toolkits The BMC II Web Services Server package has been tested against and found compatible with the following web services toolkits: Table 5

Compatible toolkits

Vendor

Toolkit

Systinet

WASP Server for C++ 4.6

Microsoft

Visual C# .NET 2003

Apache

Axis 1_3, Axis 1_4

OpenSSL

OpenSSL 0.9.6

OpenSSL compatibility The BMC II Web Services Server is compatible with version 0.9.6 of OpenSSL.

Chapter 2

Installation

23

Disk space requirements

Disk space requirements The BMC II Web Services Server package requires minimal disk space. For Windowsbased systems, you need approximately 40 MB of disk space; for UNIX®-based systems, you need approximately 30 MB of disk space.

Installing the web services server package This section describes how to install the BMC II Web Services Server using the executable that you have downloaded from the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

NOTE The BMC II Web Services Server is also installed automatically with the v. 7.1 BMC Impact Solutions Installation package when you select the Enable Web Services for Event Integration check box. The BMC II Web Services Server is installed with the BMC Impact Administration Server.

Your installation tasks consist of the following options: ■ ■

■

■ ■

defining an installation directory on the target system if not using the default specifying port numbers for the BMC II Web Services Server and the WSCELL event listener choosing which component or components (server, sample client code, or both) to install installing the component files into the installation directory defining environment variables

This task describes how to install the BMC Impact Integration Web Services Server package on the following operating systems: ■ ■ ■ ■ ■

24

Windows Linux Solaris HP-UX AIX


Installing the web services server package

Before you begin ■

Uninstall any earlier version of the BMC Impact Integration Web Services Server. See “Uninstalling the web services server package” on page 34 for the procedure. Before uninstalling an earlier version, you may want to save any customized mcell.dir, iiws.conf, or iiws.selector files.

■

By default, the BMC II Web Services Server (by means of the HTTP transport server) and the WSCELL event listener connect to BMC IM cells through port numbers 6070 and 19999, respectively. To verify that these ports are available, perform the following procedure. 1. In a Command Prompt or in a terminal window, enter the following command: netstat -a -n

It returns output that displays all connections and listening ports, together with their addresses and port numbers. 2. If the default ports are in use, determine which port numbers you will use and change the defaults when prompted to do so during the installation. You can also change the port numbers after installation by editing the server configuration file. See “Updating default port numbers post installation” on page 55. ■

■

Windows users must install the package under an administrator account or an account with administrator privileges. Linux, Solaris, HP-UX, and AIX users can install under a local account.

NOTE Linux, Solaris, HP-UX, and AIX users. The server connects through port number 6070 by default. If you intend to use a reserved port (port number 1024 or lower), you should install under the root account to ensure that you can access the selected reserved port.

■

Know the location of your Java Runtime Environment (JRE™). The installation program tries to locate it in certain directories. If it does not find it, the installation program exits. ■

On UNIX platforms, you can enter the whereis command (for example, whereis java) to locate your Java home directory. Or you can use the find . | grep or a variation of the find command to locate the JRE. You should change directory to the Java home directory to make sure that it contains the JRE. On UNIX platforms, to instruct the installation script to use a particular JRE, enter the following command: ./installScript -is:javahome /directoryPathToJRE

Chapter 2

Installation

25


■

■

On Windows platforms, you can verify your Java version by entering java -version from a Command Prompt window. You may need to edit your Windows PATH variable by adding the file path to your JRE in the Windows PATH definition. You may also need to define a Java_Home and a ClassPath system variable.

AIX users. Your AIX system requires the XLC runtime libraries 6.0.0.11. If your AIX system does not contain these libraries, you must download and install these libraries before trying to install the BMC II Web Services Server package.

To install the Web Services package on Microsoft Windows 1 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

2 After you log in, from the main menu choose Developer Centers => BMC Infrastructure Management. You can navigate to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the Web Services Server component for the latest download instructions. The MS Windows downloadable file is IIWS71_00.exe. It is a zipped file from which you must extract the setupwin32.exe file.

3 After you extract the files, double-click setupwin32.exe to launch the installation. The InstallShield Wizard is opened, and the Welcome screen is displayed.

4 Click Next to continue. BMC Software—SDK License Agreement is displayed. For the text of this agreement, see the back matter in this guide.

5 Read the license agreement, and click the radio box to indicate that you accept the terms.

6 Click Next to continue. The installation directory window is displayed. 7 Perform any one of the following actions: ■

Accept the default directory in the Directory Name field.

■

Click Browse to search for another directory path on the file system

■

Enter a custom directory path in the Directory Name text field.

8 Click Next to continue. The next window asks that you enter the BMC II Web Services Server port number and the MCELL event listener port number. Accept the default port number values or specify your own. 26



9 Click Next to continue. The next window asks whether you want to install the BMC II Web Services as a system service. By default, it is installed as a system service. If you accept the default value, go to 10 on page 27. Clear the check box if you intend to start the service manually. Skip to 11 on page 27.

10 Click Next to continue. Specify the name of the service. You can accept the default name (IIWS) or enter your own. If you have more than one BMC II Web Services Server installation of the same version on the host, enter a service name different from the existing service name.

11 Click Next to continue. Decide whether to choose a typical or a custom installation. The typical installation installs both the server and the sample client code in the specified installation directory. The custom installation option lets you choose to install the server, the sample client code, or both.

12 Click Next to continue. The summary window is displayed, showing your installation selections.

NOTE You can click Back to return to a previous window and change a selection.

13 Click Install to start the installation process. The program extracts the files and installs them in the specified installation directory. When the installation is complete, a window displays to tell you that the installation is successful or that the program encountered errors during installation.

14 Click Finish if the installation is successful. If the installation encountered errors, review the log file to locate the relevant error.

15 See “Installation directory contents” on page 29 to review the installation directory structure and contents, and see “Post-installation” on page 31 to decide your next step. If you installed the server as a service (IIWS is the default name), the service is started automatically when the installation is complete.

To Install the Web Services package on Linux, Solaris, AIX, or HP-UX (X Window System) If you are installing on a remote system, be sure the $DISPLAY variable is set to the remote host and that you have access to the X Window System on the remote host.

Chapter 2

Installation

27


Contact your system administrator if you have questions regarding instructions and command syntax for running X Window System.

1 Verify that the X Window System is running. If the X Window System is not running, enter the startup command.

2 Access the login page of the BMC Developer Network (BMCDN) website at http://developer.bmc.com.

3 After you log in, from the main menu choose Developer Centers => BMC Infrastructure Management. You can navigate to the web page where you can download the toolkit or toolkit component that you want. Refer to the release notes of the Web Services Server component for the latest download instructions. The UNIX or Linux downloadable file for the BMC II Web Services Server is IIWS71_00.tar.gz. The MS Windows downloadable file is IIWS71_00.exe. It is a zipped file that also contains the UNIX and Linux distribution files that you can deploy from a Windows system.

4 After you extract the files into the current working directory, locate and execute the appropriate distribution file for your operating system. See Table 6 on page 28. Table 6

UNIX distribution files

File name

Operating system

Command

setupaix.bin

AIX

./setupaix.bin

setupHP11.bin

HP-UX 11

./setupHP11.bin

setupLinux.bin

Linux

./setupLinux.bin

setupSolaris.bin

Solaris

./setupSolaris.bin

NOTE You can omit the dot-slash (./) if the directory in which the distribution file resides is defined in your system’s $PATH variable.

5 Follow the online instructions in the InstallShield wizard. See “To install the Web Services package on Microsoft Windows” on page 26 for the sequence of installation windows. If you choose to install the BMC II Web Services as a daemon, you must manually start the BMC II Web Services Server for its first-time startup. Thereafter it will run automatically in the background. See “Starting and stopping the BMC II Web Services Server” on page 59 for more information.

28


Installation directory contents

TIP Note the name of the installation directory. You will need to enter it later when you define environment variables.

To install the web services package on Linux, Solaris, HP-UX, or AIX (console option) To install the web services package in a non-graphical mode, launch the installation using the console command. For example, if you are running the installation from a remote host and do not have access to the X Window System on the remote host, use the console command to launch the installation in non-graphical mode. Contact your system administrator if you have questions regarding instructions and command syntax for running the console command.

1 Follow Steps 2 through 5 under “To Install the Web Services package on Linux, Solaris, AIX, or HP-UX (X Window System)” on page 27 to find and launch the installation script.

NOTE You can omit the dot-slash (./) if the directory in which the distribution file resides is defined in the $PATH variable.

2 Follow the prompts in the installation script. You must accept the license agreement to proceed with the installation.

Installation directory contents Table 7 on page 30 describes the directory contents of the installation package:

Chapter 2

Installation

29

Installation directory contents

Table 7

Directory contents

Directory

Description

bin

contains the ImpactManager.wsdl file along with its accompanying schema definition files, library files, and the executable files for the web services server. UNIX users already have execute permissions on the server executable files.

cache

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 events are received. The size of the cache directory is controlled by the RecvBufferSize parameter defined in the iiws.conf file.

conf

contains XML configuration files including those for the BMC II Web Services Server, http server, and openSSL components

locale

contains the language support message catalog files and the iiws.load file. Do not modify these files.

mcell

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

openssl

contains the script for generating the server OpenSSL certificate. It also includes a sample private key and a sample public key, along with self-signed trusted certificates that can be shared by client and server.

samples

contains the sample client configuration files for C++, C# , and Java in waspc, .NET, and AXIS directories. It also includes the EventListener.wsdl and listenercfg.xml files, both of which are required to build a listener client. The samples directory is not included in the BMC Portal installation of the BMC II Web Services Server.

_uninst

uninstall directory containing the uninstaller executable and related files

The installation directory also includes the following files: ■

log.txt – installation log file that is generated if errors are recorded during

installation ■

removeservices.bat (Windows) or removedaemon.sh (UNIX) – used by the uninstall

script when you uninstall the BMC II Web Services Server.

30


Post-installation

NOTE After you start the BMC II Web Services Server, log and tmp directories are created under the drive:\installDirectory or $installDirectory path. The log directory stores events on the BMC II Web Services Server during non-reliable subscription connections established by clients. The persist.dat file acts as a persistent buffer for outgoing events and the uniqueId.dat file acts as a counter for the events. The tmp directory stores a server log file.

Post-installation To troubleshoot installation errors, refer to the output written to the InstallShield or terminal window. If you are using Windows, go to “Setting environment variables under Microsoft Windows” on page 31. If you are using Solaris, Linux, HP-UX, or AIX, go to “Setting environment variables under Solaris, Linux, HP-UX, and AIX” on page 32.

Setting environment variables under Microsoft Windows You can edit the system %PATH% environment variable to add the following directory links: ■ ■

installDirectory installDirectory\bin

Before you begin The exact steps for defining environment variables vary from one Windows operating system to another. Refer to your Windows documentation or online help for information on defining environment variables in your version of Windows.

To set environment variables (Windows) 1 Open the Environment Variables dialog box either from your desktop or from the Start menu

2 Under System Variables, select the %PATH% variable, and click Edit. 3 In the dialog box, add the following links to the path string: installDirectory; installDirectory\bin.

Chapter 2

Installation

31

Setting environment variables under Solaris, Linux, HP-UX, and AIX

Include the drive letter to specify the disk drive where the BMC Impact Integration Web Services Server package is installed, and use a trailing semicolon to separate entries. For example, if the installDirectory is called imws, and the installation is on the C drive, your entries would appear as follows: C:\imws\; C:\imws\bin

4 Click OK to close the dialog box and return to the Environment Variables dialog box. Continue to click OK in the succeeding dialog boxes to end the task.

Where to go from here Go to Chapter 3, “Configuration,”to begin configuring the BMC II Web Services Server.

Setting environment variables under Solaris, Linux, HP-UX, and AIX You can ■

add directory paths to the $PATH environment variable

You must add the library path to the ■

$LD_LIBRARY_PATH environment variable under Solaris and Linux

■

$SHLIB_PATH environment variable under HP-UX

■

$LIBPATH environment variable under AIX

NOTE You can define these variables in your .profile file under the Bourne or Korn shell, in your .cshrc file under C shell, or in your .bashrc file under Bash shell. You can source the file to set the variables.

To add directory paths to the $PATH Open a terminal window, and enter the appropriate command syntax depending on your shell script:

32


Setting environment variables under Solaris, Linux, HP-UX, and AIX

Bourne, Korn, or Bash Shell PATH=$PATH:/installDirectory:/installDirectory/bin;export PATH

C Shell setenv PATH $PATH:installDirectory:installDirectory/bin

To define the $LD_LIBRARY_PATH variable (Solaris and Linux) Open a terminal window, and enter the appropriate syntax for your shell:

Bourne, Korn, or Bash Shell LD_LIBRARY_PATH=/installDirectory/bin;export LD_LIBRARY_PATH

C Shell setenv LD_LIBRARY_PATH /installDirectory/bin

To define the $SHLIB_PATH variable (HP-UX) Open a terminal window, and enter the appropriate syntax for your shell:

Bourne, Korn, or Bash Shell SHLIB_PATH=/installDirectory/bin;export SHLIB_PATH

C Shell setenv SHLIB_PATH /installDirectory/bin

To define the $LIBPATH variable (AIX) Open a terminal window, and enter the appropriate syntax for your shell:

Bourne, Korn, or Bash Shell LIBPATH=/installDirectory/bin;export LIBPATH

C Shell setenv LIBPATH /installDirectory/bin

Chapter 2

Installation

33

Uninstalling the web services server package

Where to go from here Go to Chapter 3, “Configuration” for information on how to configure your BMC II Web Services Server.

Uninstalling the web services server package Before you begin On UNIX platforms, ensure that the BMC II Web Services Server is stopped. On Windows platforms, remove the BMC II Web Services Server service by running the removeservice.bat file from a Command Prompt window. The removeservice.bat file is located in your BMC II Web Services Server installDirectory, from which you can execute it.

To uninstall the web services package on Microsoft Windows NOTE The exact steps for uninstalling a product vary somewhat among the different supported Windows operating systems. This procedure describes the general steps that are true across all supported Windows operating systems.

1 From the task bar, choose Start => Settings => Control Panel. 2 In the Control Panel window, choose Add/Remove Programs. 3 In the Add/Remove Programs window, scroll down until you locate the Impact Integration Web Services entry.

4 Select the Impact Integration Web Services entry, and click Change/Remove. The Uninstaller wizard is opened.

5 Click Next to continue. 6 Follow the prompts in the Uninstaller wizard. NOTE If you have created multiple instances of the web services server or client on the same host and have changed their directory location to a folder outside the original installation directory, the Uninstaller is not going to remove the component. You have to delete the folder manually.

34



The next window lists the results of the operation, indicating whether the uninstallation is successful.

7 If successful, click Finish. The components are removed from the specified installation directory.

8 Manually remove the remaining folders and files. To uninstall the web services package on Linux, Solaris, HP-UX, or AIX 1 Change directory to the uninstall directory -uninst. 2 Run the following command: ./uninstaller.bin

3 Follow the steps as directed and manually remove any remaining files. NOTE If you have created multiple instances of the web services server and placed them in different directory paths, you have to manually remove them also.

Chapter 2

Installation

35


36


Chapter

3

3

Configuration This chapter describes both the required configuration tasks that enable your BMC II Web Services Server connection and the optional tasks, such as establishing high availability cells. It also describes basic operations, such as starting and stopping the server, and it provides an overview of administrative tasks. Required configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 How to synchronize BMC II Web Services Server and BMC IM cell connections. . 38 Troubleshooting tip: BMC II Web Services Server fails to reconnect . . . . . . . . . . 44 Defining Propagate rules or event propagation policies for BMC IM cells . . . . . 45 Optional configuration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Configuring high availability cells for the BMC II Web Services Server . . . . . . . 51 Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Updating default port numbers post installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Configuring Attributes in the BMC II Web Services Server . . . . . . . . . . . . . . . . . . 57 Modifying the default BMC II Web Services Server log . . . . . . . . . . . . . . . . . . . . . 58 Starting and stopping the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . 59 Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Connecting to BMC II Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Installing multiple instances of the BMC II Web Services Server . . . . . . . . . . . . . . . . . 62 When to assign a unique server instance name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Administering the BMC II Web Services Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 3 Configuration

37

Required configuration tasks

Required configuration tasks Configuring the BMC II Web Services Server consists of the following required tasks: Table 8

Required configuration tasks

Task

Description

Page

Synchronizing BMC II Web Services Server and BMC IM cell connections

38 To send events to or query against specific BMC Impact Manager instances, you must enter their cell data in the mcell.dir of the BMC II Web Services Server. To receive events from BMC IM cells, you must enter data about the WSCELL event listener in the mcell.dir file of each BMC Impact Manager instance that sends events to the server.

Defining Propagate rules or event propagation policies for BMC IM cells

To receive events (aside from state change events) from BMC IM cells, 45 you must define Propagate rules or event propagation policies that specify the WSCELL entry of the BMC II Web Services Server. Note: You do not need to define Propagate rules or event propagation policies to receive service component state change events. After you register the BMC II Web Services Server instance with the SIM cell, the cell automatically sends the state change events to the server. See “Registering and receiving service component state change events” on page 98 for more information.

How to synchronize 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

In the BMC Impact Manager instance, its mcell.dir file must specify ■ ■

other cells that it connects with the WSCELL event listener entry of the BMC II Web Services Server to which it sends or propagates events

NOTE You only need to add the WSCELL entry to the mcell.dir of the cell if it is sending events to the BMC II Web Services Server.

38


How to synchronize BMC II Web Services Server and BMC IM cell connections

Table 9 on page 39 shows the default directory location of the mcell.dir file in the BMC Impact Manager and in BMC Impact Integration Web Services Server installations. Table 9

Location of mcell.dir Files

Operating System

BMC Impact Integration Web BMC Impact Manager instance Services Server instance

Windows

%MCELL_HOME%\etc

drive:\installDirectory\mcell

Solaris, Linux, HP-UX, AIX

$MCELL_HOME/etc

installDirectory/mcell

mcell.dir entries for multiple cells that comprise a service model To ensure consistent communication among multiple cells containing components of a service model, BMC recommends that you make all cell entries uniform. That is, if a service model is published across cells A, B, C, and D, then the mcell.dir file of each cell should reference all cells in the model. For example, the mcell.dir file of cell A would contain the following entries: cell cell cell cell

cellA cellB cellC cellD

MC MC MC MC

myIMComputer:1828 myIMComputer1:1828 myIMComputer2:1828 myIMComputer3:1828

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

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


39


Table 10

mcell.dir configurations for queries

Purpose of BMC II Web Services Server instance To query events, data, or a service model

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

its local WSCELL entry the cell or cells that it communicates with, including all cells that comprise a service model

■ ■

the local cell entry all cells that it communicates with, including all cells that comprise a service model

Figure 2 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. The mcell.dir file contains entries for all the cells that comprise the service model. Figure 2 cell cell cell cell

mcell.dir example: BMC II Web Services Server WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC

myWSComputer:19999 myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828

Figure 3 on page 40 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 no events are being sent from the cell. Figure 3 cell cell cell

mcell.dir example: BMC IM cell cellConnect MC cellConnect 1 MC cellConnect 2 MC

myIMComputer:1828 secondIMComputer:1828 thirdIMComputer:1828

Sending events Table 11 on page 40 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that sends events. The mcell.dir entries for both the BMC II Web Services Server and the BMC IM instances are identical to those of a query implementation. Table 11

mcell.dir configurations for sending events

Purpose of BMC II Web Services Server instance To send events

mcell.dir entries: BMC II Web Services Server instance ■ ■

40

its local WSCELL entry the cell or cells that it communicates with, including all cells that comprise a service model

mcell.dir entries: BMC IM instances ■ ■

the local cell entry all cells that it communicates with, including all cells that comprise a service model



Receiving events Table 12 on page 41 lists the mcell.dir configuration entries of a BMC II Web Services Server implementation that receives events. Whenever a BMC IM cell sends events to a BMC II Web Services Server instance, its mcell.dir must contain the WSCELL entry that points to the server that receives the events. Table 12

mcell.dir configurations for receiving events

Purpose of BMC II Web Services Server instance To receive events, including state change events, from connected cells

mcell.dir entries: BMC II Web Services Server instance ■ ■

its local WSCELL entry the cell or cells that it communicates with, including all cells that comprise the service model

mcell.dir entries: BMC IM instances ■

■ ■

the WSCELL entry identifying the BMC II Web Services Server instance to which it is sending events the local cell entry all cells that it communicates with, including all cells that comprise the service model

Figure 4 on page 41 continues with the example shown in Figure 2 on page 40, in which the mcell.dir of the BMC II Web Services Server contains the three cells that comprise the service model to which the server is connected. You can follow this example to list cells that the server ■ ■ ■

queries sends events to receives events from

NOTE Except for state change events, you must define a Propagate rule or an event propagation policy for each cell from which the server receives events. See “Defining Propagate rules or event propagation policies for BMC IM cells” on page 45 and also for more information. Figure 4 cell cell cell cell

mcell.dir example: BMC II Web Services Server WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC


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


41


Figure 5 cell cell cell cell

mcell.dir example: BMC IM cell WSCELL MC cellConnect MC cellConnect 1 MC cellConnect 2 MC


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.

Before you begin To verify whether the default port numbers are available, run the netstat -a -n command. See “Installing the web services server package” on page 24 for more information.

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

cellConnect MC WSCELL MC

myIMComputer:1828 myWSComputer:19999

3 If the cell is sending events to multiple BMC II Web Services Server instances, then add the corresponding WSCELL entries. Specify a unique combination of name, IP address (or host name), and port number for each WSCELL entry.

42



For example, if the server instances are on different systems, you can make the WSCELL entries as shown in the following figure: cell cell cell cell

cellConnect MC WSCELL MC WSCELL1 MC WSCELL2 MC

myIMComputer:1828 myWSComputer:19999 secondWSComputer:19999 thirdWSComputer:19999

Because each BMC II Web Services Server instance is on a different host system, you do not have to specify a distinct port number for each WSCELL event listener. If the server instances are on the same system, your WSCELL entries might be written as in the following figure: cell cell cell cell

cellConnect MC WSCELL MC WSCELL1 MC WSCELL2 MC

myIMComputer:1828 myWSComputer:19999 myWSComputer:20000 myWSComputer:20001

Because the server instances reside on the same system, the WSCELL entries must have a unique port number. See “To Change the Port Number of the WSCELL event listener” on page 57 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.

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 event propagation policies for BMC IM cells” on page 45. Alternatively, you can add a Propagate policy through the BMC Impact Explorer GUI.

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


43

Troubleshooting tip: BMC II Web Services Server fails to reconnect

1 In a text editor, open the mcell.dir file located under drive:\installDirectory\mcell or installDirectory/mcell.

2 Add the cell data for each BMC Impact Manager cell that you intend to connect to, as in the following example: cell cell cell cell cell

WSCELL MC cellConnect MC cellConnect1 MC cellConnect2 MC cellConnect3 MC

127.0.0.1:19999 myIMComputer:1828 myIMComputer1:1828 myIMComputer2:1828 myIMComputer3:1828

Guidelines ■

■

Do not change the local host IP address of 127.0.0.1 of the WSCELL entry in the mcell.dir file of the BMC II Web Services Server. If you intend to query or communicate with a service model, include all cells that comprise the service model in the mcell.dir file.

3 Save and close the file. 4 Start or restart the server. If you have other configuration changes to make, you can start or restart the server when you are finished. See “Starting and stopping the BMC II Web Services Server” on page 59.

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

44

■

wait a few minutes before you restart the BMC II Web Services Server; or

■

change the listener port number defined in the server’s mcell. dir file to some other available port



If you change the WSCELL port number entry in the server’s mcell.dir file, remember also to change it in the mcell.dir files of all cells that send events to the server.

Defining Propagate rules or event propagation policies for BMC IM cells To enable the BMC II Web Services Server to receive events from a BMC IM cell and pass the events on to a subscribing client, you must do one of the following: ■

add one or more Propagate rules to the KB of the BMC Impact Manager instance that is sending the events

■

define a event propagation policy in the BMC Impact Explorer that specifies the event criteria

NOTE You do not need to define a Propagate rule or event propagation policy to receive service component s state change events. See “Registering and receiving service component state change events” on page 98 for more information.

The Propagate rule or event propagation policy specifies that the BMC Impact Manager instance sends 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 an event propagation policy. Figure 6 on page 46 depicts three BMC Impact Manager instances that are sending events to the WSCELL event listener. You define a Propagate rule or an event propagation policy for each instance, specifying the WSCELL event listener as the destination of the event.


45


Figure 6

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 an event propagation policy. Figure 7 on page 47 depicts this example.

46



Figure 7

Event propagation: many instances to many servers

In Figure 7, 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 an event propagation 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.

TIP When defining your Propagate rule or event propagation policy, be sure to specify the name of the WSCELL entry exactly as it is defined in the mcell.dir file.

Example Propagate rules This section describes sample Propagate rules and describes how to manually add a Propagate rule to the cell’s KB. Refer to the BMC Impact Solutions:Knowledge Base Development for additional information about Propagate rules. (For information on creating an event propagation policy, see the BMC Impact Solutions:Administration guide.)


47


A Propagate rule might be written as follows: propagate to_WSCELL: EVENT ($EV) to WSCELL END

If you are using the same selector criteria and sending the same events to multiple BMC II Web Services Servers (multiple WSCELL entries WSCELL and WSCELL1, for example), then your Propagate rule might look as follows: propagate to_WSCELL: EVENT ($EV) to_all WSCELL, WSCELL1 END

If you are using different selector criteria to send different events to each BMC II Web Services Server, then you would write a different Propagate rule for each WSCELL. If you are sending different events to WSCELL and WSCELL1, your Propagate rules might look as follows: propagate to_WSCELL: EVENT ($EV) to WSCELL END propagate to_WSCELL1: EVENT ($EV) to WSCELL1 END

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.

48



To create a Propagate rule 1 In a text editor, open an existing .mrl file, which you can find under the drive:\installDirectory\etc\cellName\kb\rules or installDirectory/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-2007 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:\installDirectory\etc\cellName\kb\rules or installDirectory/etc/cellName/kb/rules.

2 Add the name of the .mrl file containing the new Propagate rule without the file extension.


49


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:\installDirectory\etc\cellName\kb or installDirectory/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 Microsoft 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

To restart the BMC Impact Manager instance in Linux, Solaris, or HP-UX 1 In a terminal window, enter the following command: mkill -n cellName

2 Then enter the start command: mcell -n cellName

50


Optional configuration tasks

Optional configuration tasks You can configure high availability cells for the BMC II Web Services Server to ensure a consistent connection in the event that the primary cell fails. The installation routine sets the default values for port numbers, server attributes, and log files. However, you can modify these values after installation. Table 13 on page 51 lists the optional configuration tasks. Table 13

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 51 the primary one in case the primary server fails. In this way, the BMC II Web Services Server can communicate with a secondary cell server until the primary one returns online.

Configuring high availability cells for BMC II Web Services Server in the BPM environment

You can configure an HA pair to accommodate a primary and a backup web services server in the BMC Performance Manager (BPM) environment.

54

Updating default port numbers post installation

You can update these port numbers after installation if a port number conflict develops.

55

Configuring attributes in the BMC II Web Services Server

You can specify the values for certain server attributes. You can define the size of event queues if are using query or polling calls in your client.

57

Default logging

This topic describes the different log files that the BMC II Web Services Server uses.

58

Configuring high availability cells for the BMC II Web Services Server NOTE Refer to the BMC Impact Solutions: General Administration guide for detailed information about high availability (HA) implementation.

To maximize availability, BMC recommends that you install your primary cell on one computer and your secondary cell on a different computer. Both primary and secondary cells should be installed and running on different images of the same operating system. Your HA implementation can take many forms, but two likely ones are depicted in the following figures.


51

Configuring high availability cells for the BMC II Web Services Server

Figure 8 on page 52 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.) Figure 8

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

Figure 9 on page 53 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.

52


Configuring high availability cells for the BMC II Web Services Server

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

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.


53

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

■

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.

■

Restart the cell servers.

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 10 on page 55 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.

54



Figure 10

HA implementation scenario for BPM and BMC II Web Services Server

Updating default port numbers post installation Table 14 lists the default port numbers that the BMC II Web Services Server uses. If these 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. Table 14

Default port numbers Default Port Number

Component

File

HTTP transport server

Windows: drive:\installDirectory\conf\ servercfg.xml Solaris, Linux, HP-UX, AIX: installDirectory/conf/servercfg.xml

6070

WSCELL

Windows: drive:\installDirectory\mcell\mcell.dir Solaris, Linux, HP-UX, AIX: installDirectory/mcell/mcell.dir

19999


55


The HTTP transport server, defined in the servercfg.xml file, specifies the port number through which the BMC II Web Services client exchanges request-response messages with the BMC II Web Services Server. The WSCELL is described in “WSCELL event listener” on page 18. Each instance of the BMC II Web Services Server must have an associated WSCELL entry.

To Change the port number on the BMC Impact Integration Web Services Server 1 In a text editor, open the servercfg.xml file located under drive:\installDirectory\conf or installDirectory/conf. Figure 11 on page 56 shows the default declaration of the servercfg.xml file. The port number attribute is highlighted in bold. The hts:port attribute specifies the default port number 6070 for the server port. Figure 11

servercfg.xml file: default declaration

56


Configuring Attributes in the BMC II Web Services Server

WASPOpenSSL.dll WASPOpenSSLDbg.dll Contents from servercfg.security.xml file openssl/certs wsdlc %installDirectory%\bin\ImpactManager.wsdl ImpactManager

where ImpactManager is the name of the web services project. You generate sets of files, including files that contain the client stub information, data types, and structures. In the Systinet WASP Server for C++ toolkit, you generate three pairs of files, each consisting of a source and a header file. One pair is generated for the Impact Integration Web Services client; one for the server; and one for the data structures. These files are created in the directory from which you executed the WSDL sourcecode generator. In the Systinet WASP Server for C++ Toolkit, the wsdlc utility generates the following stub files in its home directory: Component

Source file name

Header file name

Client

projectName.cpp

projectName.h

Server

projectNameImpl.cpp

projectNameImpl.h

Data structures

projectNameStructs.cpp

projectNameStructs.h

.NET C# toolkit sample Using the WSDL utility in the .NET C# toolkit, you can generate the client stubs from the URL that points to the BMC II Web Services WSDL: http://hostName:6070/imapi/.

NOTE You must include the ending slash (/) after the service name imapi in the URL. Port number 6070 is the default port number of the BMC II Web Services server.

To generate the client stubs, open a Visual Studio .NET Command Prompt window, navigate to the appropriate directory path, and enter the following command: wsdl http://hostName:6070/imapi/

76


Apache Axis toolkit sample

Your output should look similar to the following text: Writing file ‘C:\directoryPath\src\ImpactManager.cs’

NOTE If you are generating the client stubs from the URL, you may receive schema validation errors before you receive the message that the ImpactManager.cs file is being written.

Using the WSDL utility, you can also generate client stubs from the hardcopy WSDL and schema definition files. Open a Visual Studio .NET Command Prompt, navigate to the appropriate directory path, and enter a command string similar to the following example: wsdl drive:\installDirectory\bin\ImpactManager.wsdl drive:\installDirectory\bin\BasicTypes.xsd drive:\installDirectory\bin\Event.xsd drive:\installDirectory\bin\ImapiTypes.xsd

You should receive the output Writing file ‘C:\directoryPath\src\ImpactManager.cs’. In the .NET C# toolkit, you can also generate the client stub dynamically from within the .NET GUI.

1 Create a .NET project for the BMC II Web Services. 2 From the Project => Add Web Reference command, enter the URL that points to the BMC II Web Services WSDL: http://hostName:6070/imapi/.

3 In the C# source file, add the reference to the stub, for example, “using nameofproject.webreferencename;”.

Apache Axis toolkit sample Under the installDirectory\samples\Axis folder, you can find in separate subfolders a series of Apache Axis Java programming examples for defining queries, sending events, and receiving events. Each example has its own ReadMe file that explains how to build and run it. The ant_build.bat file, which is the build script, calls the wsdl-build.xml file to generate the Java stubs from the ImpactManager.wsdl. The stub code is located under the runtime directory of each sample. The ant_build.bat file also generates two jar files, which are copied under the lib subdirectory. The iiws-client-stub.jar is the jar file generated from the stub code, and the sample-name.jar file is generated from the sample code itself.

Chapter 5


77

Using the NO_INOUT operations to return single elements for the Axis toolkit

You can find the stub files under the following runtime directory: Figure 13

Runtime directory folders for stub files

Using the NO_INOUT operations to return single elements for the Axis toolkit The ImpactManager.wsdl defines the following operations with the NO_INOUT extensions: ■ ■ ■ ■

bmciiws_connect_NO_INOUT bmciiws_getEvents_NO_INOUT bmciiws_getQueryResult_NO_INOUT bmciiws_retrieveQueryResults_NO_INOUT

These NO_INOUT operations are modified versions of the original operations (bmciiws_connect, bmciiws_getEvents, and so forth), which return two response elements in their output. In their output, the NO_INOUT versions return a single structure instead of two elements. The NO_INOUT operations are designed to accommodate web service toolkits, such as Axis, that return only one element in their response message to a client request.

Deciding which stub operations to use After you generate the client proxy code, review the output. You may need to edit the generated stub files. Review the generated client proxy code to help you decide which operations to use in your client. The client files, which are generated from the ImpactManager.wsdl, describe how the toolkit invokes the functions or methods and their parameters in the target programming language.

78


Deciding which stub operations to use

NOTE Operations is a WSDL term. If you are programming in C/C++, substitute the term functions. If you are programming in Java, substitute the term methods.

These functions or methods are generated from the operations that are defined in the ImpactManager.wsdl. These operations are summarized in the following table: Table 15

Summary of Available Operations (part 1 of 2)

Operation

Description

bmciiws_getCellInfo

to identify BMC Impact Manager instances that are connected to the BMC Impact Integration Web Services Server

bmciiws_connect

to connect to a specified BMC Impact Manager instance

bmciiws_send

to send a client event or data object to the specified BMC Impact Manager instance

bmciiws_getFilterNames

to retrieve the available selector names to which the client can subscribe

bmciiws_subscribe

to subscribe to a specified event selector for a particular client to receive events. If this is a listener client, then a callback is supplied. Otherwise, if this is a polling client, the callback is set to ““. This operation is included for backwards compatibility with earlier versions of the BMC II Web Services Server toolkit. You should now use bmciiws_subscribe_reliable to initiate the subscription requests.

bmciiws_subscribe_reliable

to enable a reliable subscription to a specified event selector for a particular client to receive events. (A listener client also supplies a callback URL.) If the Reliable indicator is set to False, then the subscription is considered non-reliable.

bmciiws_ack

to enable a client that has a reliable subscription to send an acknowledgement to the BMC II Web Services server indicating that it has received the requested events. The BMC II Web Services Server removes the forwarded events from its cache subdirectory.

bmciiws_getEvents

to request a specified number of events matching a defined event selector for a particular client. Used in polling calls

bmciiws_unsubscribe

to unsubscribe from the specified event selector in the BMC Impact Manager instance

bmciiws_disconnect

to disconnect from the BMC Impact Manager instance

bmciiws_queryEvents

to query a specific BMC Impact Manager instance for events

bmciiws_queryData

to query a specific BMC Impact Manager instance for data

bmciiws_queryEventByID

to query a specific BMC Impact Manager instance for events matching a specified BMC Impact Manager event ID

bmciiws_queryDataByID

to query a specific BMC Impact Manager instance for data objects matching a specified BMC Impact Manager data ID

bmciiws_queryEventsByDate

to query a specific BMC Impact Manager instance for events that belong to specified class and that have occurred within a specified date range

Chapter 5


79

Deciding which stub operations to use

Table 15

Summary of Available Operations (part 2 of 2)

Operation

Description

bmciiws_queryComponent

to query a specified component object to retrieve its component data attributes

bmciiws_queryComponentsByStatus

to query service components that MC_SM_COMPONENT_STATUS values in the specified range and which belong to the specified base class or subclass

bmciiws_queryComponentStatus

to query a component and return its status, as defined by its computed component status: status, self_status, computed_status, impact_status, and manual_status

bmciiws_queryComponentEvents

to query service components for direct and impact events. You have the option of retrieving only impact events.

bmciiws_queryComponentsBy Condition

to query for an array of service model components that match the special Master Rule Language (MRL) conditions. These conditions follow the syntax and conventions of the MRL where-clause selection criteria.

bmciiws_queryModelImpact

to query for possible consumer components of the specified component ID

bmciiws_queryPossibleRootCause

to query for a component or components that are the possible root cause of a specified component’s status

bmciiws_queryClassDefinitions

to query a specific base class and its subclasses for the class and slot definitions or to query a specific class for its class definition and slot definitions

bmciiws_getQueryResultCount

to obtain the total number of events or data objects that have been returned by the query

bmciiws_getQueryResult

to obtain a specified number of events or data objects to satisfy the query

bmciiws_endQuery

to end the query cycle and disconnect from the specified BMC Impact Manager instance

bmciiws_setMaintenanceMode

to request to place a specified component in maintenance mode

bmciiws_setManualStatus

to request to set a designated manual status on the specified component

bmciiws_registerStateChange

to register your client with a BMC SIM cell to receive state change events

bmciiws_unregisterStateChange

to remove the registration ID assigned to the request to receive state change events, thereby stopping your integration from receiving state change events

NOTE You can read the guidelines for building different types of clients to determine which operations you should use. See “Implementing the send feature” on page 81, “Listener client (reliable or non-reliable subscription)” on page 95, or “Implementing the receive feature” on page 88.

80


Compiling the client code

Review the generated source files that describe the data structures and their types. These structures and types are generated from the data types defined in the ImpactManager.wsdl and in the imported schema definition files. The generated source files describe how the toolkit uses the data structures and types in the target programming language. Review any generated source files that describe how the toolkit uses the code in the target programming language on the BMC II Web Services server.

NOTE If you are programming in the C/C++ language, the source-code generator also supplies header files (*.h).

For additional information on the operations and data types as they are defined in the ImpactManager.wsdl, see the BMC Impact Integration Developer’s Kit Web Services Server

Reference Guide.

Compiling the client code When you compile your custom client code, include the source files for the client stub and for any data structure stub. Also include the header files if you are using the C/C++ language.

Maximum number of open outgoing connections Your integration application is limited to a maximum number of 100 open outgoing connections per session to one or more BMC IM cells. The number of incoming connections is not limited.

Implementing the send feature After you generate the client stubs and write your client source code, you can compile the client code and the client stubs to enable your client to send events, data, or both. Typically, a web services client that only sends events and data relies on synchronous event processing, but depending on your choice of toolkit, asynchronous event processing may be supported.

Chapter 5


81

How a send request is processed

EXAMPLE The WASP server for C++ toolkit supports asynchronous event processing for clients that send events.

How a send request is processed The BMC II Web Services Server receives the client requests through default port 6070 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.

Sequence of operations to use To enable a client to send events and data, call the following key operations in sequence: 1. bmciiws_connect Before you send events, you must invoke the bmciiws_connect operation. When you invoke the bmciiws_connect operation, you register with the BMC II Web Services server and connect with a specified BMC Impact Manager instance. You indicate which buffering routine you want to use, and you specify a connection ID that serves as the request/response connection handler. Because you are connecting to specific BMC Impact Manager instances, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file residing on the BMC II Web Services server. See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information. 2. bmciiws_send Invoke the bmciiws_send operation to send an event or data object to the BMC Impact Manager specified in the bmciiws_connect operation. In the bmciiws_send operation, you specify the connection ID, the response timeout interval, and the message parameters. If your client is an event provider, you can connect and continue to call the bmciiws_send operation repeatedly to send events. 3. Invoke the bmciiws_disconnect() operation to disconnect from the specified BMC Impact Manager instance and to unregister from the BMC II Web Services server.

82


Implementing the query features

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for descriptions of these operations.

Implementing the query features 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 installDirectory/log/cellName or drive:\installDirectory\log\cellName directory. The service model queries can search for and return service model information that has been published to one or more cells.

NOTE These service model queries retrieve component data that has already been published to the cell; they do not query the BMC® Atrium Configuration Management Database.

■

retrieve service model class definitions from a specific BMC IM instance The class definition query retrieves static class definition information stored in the BAROC files under the installDirectory/etc/cellName/kb/classes or the drive:\installDirectory\etc\cellName\kb\classes directory. See “bmciiws_queryClassDefinitions: class definition array” on page 86 for more information.

How a query is processed 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.

Chapter 5


83

Sequence of operations to use

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. 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 event propagation policies to push events from BMC Impact Manager instances to the WSCELL event listener residing on the BMC II Web Services Server.

Sequence of operations to use The query operations have their own connection protocol. You do not have to call the bmciiws_connect operation before calling a query. You establish a separate query connection when you call a query operation. When building your queries, invoke the following key operations in sequence: 1. One of the queries listed in Table 15 on page 79. Invoke the specific query operation first. In the specific query, you identify what you are querying for and specify the BMC Impact Manager instance to which you are connecting. A query ID is returned that is used to track all related queries in this sequence.

NOTE For the service model queries, you must enter a component ID as an input parameter. You can obtain component IDs from the service model view in the BMC Impact Explorer or from the return values of other queries, such as bmciiws_queryComponentsByCondition or bmciiws_queryComponentsByStatus.

The client can invoke multiple queries simultaneously on the same BMC Impact Manager instance connection, subject to the maximum outgoing connection restriction of 100 open connections. The volume of event and data throughput can impact the performance of the web services server.

84


Sequence of operations to use

NOTE Reliable subscription does not apply to the query functions. If you lose a query connection, all query information is lost. You must reconnect by resending the query function.

See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for more information about these query operations.

TIP As a reminder, because you are connecting to specific BMC Impact Manager instances,

you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file residing on the BMC II Web Services server. See “How to synchronize BMC II Web Services Server and BMC IM cell connections” on page 38 for more information. 2. bmciiws_getQueryResultCount The _getQueryResultCount call discovers the total number of events or data objects that are available to the query. Invoke the bmciiws_getQueryResultCount to get the total number of events or data objects that the BMC II Web Services server has retrieved in response to the specific query. This query also sends the query ID obtained by the initial query request. 3. bmciiws_getQueryResult The _getQueryResult call specifies the number of events or data objects of the total that the client wants to receive. The default value is set equal to 30. You can modify this value by changing the MaxResponseEventListSize parameter in the servercfg.xml file. See “Configuring Attributes in the BMC II Web Services Server” on page 57 for more information. You can retrieve the entire range of results at once if the result count is not too large. You can ask to retrieve a specified number of results at one time. You can continue to retrieve the specified number in successive tries until you have retrieved all the results in the range. You can also call the bmciiws_getQueryResult() operation to retrieve a specified number of events or data objects starting from a certain index point. For example, if the query result count is 50, in the bmciiws_getQueryResult() operation, you can specify a beginning point of 20 and indicate that you want to receive the next 10 events. You retrieve events 20 through 30. (This query also sends the query ID.) You can invoke multiple bmiiws_getQueryResult() operations to retrieve all the event or data objects. Then invoke bmciiws_endQuery() to terminate the query cycle.

Chapter 5


85

bmciiws_queryClassDefinitions: class definition array

4. bmciiws_endQuery The _endQuery call notifies the BMC II Web Services Server to terminate the query cycle. Invoke the bmciiws_endQuery operation to terminate the query cycle for this query. This operation sends only the query ID, which indicates to the web services server that the query is over. The client must call the bmciiws_endQuery() operation to clean up the query context in the BMC II Web Services server, to clean up the memory cache, and to close the connection with the BMC Impact Manager instance.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for descriptions of these operations.

bmciiws_queryClassDefinitions: class definition array The bmciiws_queryClassDefinitions operation returns a class definition array. You can review this description to see how the operation builds the array it returns. This example, which is only for illustrative purposes, uses the following input parameter values for the bmciiws_queryClassDefinitions operation: Parameter

Value

imname

testcmdb

queryMode

0 (indicates that the BMCII_DATA_CLASSES are being queried)

baseClase

BMC_AssetBase

className

blank

classOnly

0 (indicates that the query includes the BMC_AssetBase class and its subclasses)

Using these parameters, the bmciiws_queryClassDefinitions operation returns the following information, which has been edited to illustrate the array structure.

86


bmciiws_queryClassDefinitions: class definition array

Figure 14

bmciiws_queryClassDefinitions code sample

CLASS NAME:: BMC_AssetBase CHILDREN COUNT:: 5 CHILD INDEX[0]:: 1 CHILD INDEX[1]:: 2 CHILD INDEX[2]:: 3 CHILD INDEX[3]:: 4 CHILD INDEX[4]:: 5 CLASS PARENT INDEX:: -1 SLOTS COUNT:: 26 ----------------------------------------------SLOT NAME:: Type SLOT REP.TYPE:: * SLOT FLAGS:: rkPdh SLOT DEFAULT VALUE:: null ----------------------------------------------SLOT NAME:: Room SLOT REP.TYPE:: * SLOT FLAGS:: rkPdh LOT DEFAULT VALUE:: null ... ********************************************************* CLASS NAME:: BMC_GenericGroup CHILDREN COUNT:: 5 CHILD INDEX[0]:: 6 CHILD INDEX[1]:: 7 CHILD INDEX[2]:: 8 CHILD INDEX[3]:: 9 CHILD INDEX[4]:: 10 CLASS PARENT INDEX:: 0 SLOTS COUNT:: 0 ******************************************************* CLASS NAME:: BMC_LogicalComponent CHILDREN COUNT:: 6 CHILD INDEX[0]:: 11 CHILD INDEX[1]:: 12 CHILD INDEX[2]:: 13 CHILD INDEX[3]:: 14 CHILD INDEX[4]:: 15 CHILD INDEX[5]:: 16 CLASS PARENT INDEX:: 3 SLOTS COUNT:: 2

This return can be depicted in a flat array as shown in Figure 15 on page 88.

Chapter 5


87

Implementing the receive feature

Figure 15

Class definition array

The base class, BMC_AssetBase in this example, is assigned the parent index value -1. It has five child classes. The array of its children begins with point 0 and continues to the end of its child elements, which is point 5 in this example. The 26 slot definitions of the Slots Count belong to the class under the current focus, which is BMC_AssetBase. The class BMC_GenericGroup has a parent index of 0, the origin point of BMC_AssetBase class’s array of children. The BMC_GenericGroup has 5 child classes, beginning with point 6 and continuing through 10. Its Slots Count is empty. The class BMC_LogicalComponent has a parent index of 3, a child element from the BMC_AssetBase class’s array of children. The BMC_LogicalComponent has 6 child classes beginning with point 11 and continuing through 16. Its Slots Count is 2. Using the bmciiws_queryClassDefinitions operation, you can extend your query to all classes in the class hierarchy of the BMC IM instance. When writing your client code, you should include a for loop in which you define your child index parameters.

Implementing the receive feature You can build a client interface that receives events through polling calls or a publishsubscribe mechanism (event listener). Table 16 on page 89 describes the essential components for a client interface that receives events.

88


Selector choices

Table 16

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 event propagation policies

To receive events from BMC Impact Manager instances, you must define Propagate rules or event propagation 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. Note: You do not need to define Propagate rules or event propagation policies to receive service component state change events only. See “Registering and receiving service component state change events” on page 98 for more information.

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 which client interface you choose, polling or publish-subscribe. You can elect to use reliable subscription (reliable is set to True) to guarantee event delivery.

Selectors

Selectors define the criteria that determine which events your client receives. You specify a selector type in your subscription request.

Selector choices Table 17 lists the three basic choices: Table 17

Event selectors for subscription requests

Selector name

Description

Always matches

allows you to receive (filters in) all new events from the specified BMC IM cell

Modifies

allows you to receive only modified events from the cell

Everything

allows you to receive both original and modified events

These selectors are defined in the iiws.selector file, located under installDirectory\IIWS\mcell. The BMC II Web Services Server loads the iiws.selector file by default because it is specified in the server configuration file, servercfg.xml, which is under installDirectory\IIWS\conf. For more information on the selector file and selector processing, see “Selector file overview” on page 106.

Chapter 5


89

Polling interface

The BMC II Developer’s Kit C API also contains global selector files that you can enable. See “Supplemental message selector files” on page 121.

Polling interface Consider using the polling interface when ■ ■

port access is an issue a firewall separates networks across which you are communicating

The subscription request of a polling call contains the following parameters: ■

a selector that defines the event criteria of the event type which the client has subscribed to

■

a context ID that identifies the client which is making the subscription request The context ID can be any string identifier that is unique to BMC II Web Services server.

■

a callback URL that is not used in the polling interface. You set to equal to null, using the conventions of the programming language, or to an empty string ““.

■

a Boolean Reliable parameter that you can set to True or False

The example in the following figure shows a non-reliable subscription request for a polling client. bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable); bmciiws_subscribe_reliable (“Always matches”, “321”, “ “, “False”);

Publish-subscribe interface The publish-subscribe interface relies on an event listener server that has consistent port access to receive events. In your subscription request, you include a callback URL. The subscription request includes the following parameters:

90

■

selector name that identifies a selector which defines the event criteria of the event type that the client has subscribed to

■

a context ID that identifies the client which is making the subscription request


Reliable versus non-reliable subscription

■

a callback URL that identifies the event listener with whom the client has registered a callback

The example in the following figure shows a non-reliable subscription request for a publish-subscribe client. Use commas to separate the input arguments. bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable); bmciiws_subscribe_reliable (“Everything”, “123”, “http://listener:7070/EventListener”, “False”);

If you decide to use a publish-subscribe interface, see the EventListener.wsdl file contained in the %installDirectory%\Samples or $installDirectory/Samples subdirectory. You can extend the operations in the EventListener.wsdl, but do not modify the declarations or definitions. See Appendix C, “Sample Client Files” for more information.

Reliable versus non-reliable subscription By using the bmciiws_subscribe_reliable operation, you can establish a persistent connection with the BMC II Web Services server and the underlying 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 a cache directory (%installDirectory%\cache or $installDirectory/cache).

NOTE The bmciiws_subscribe_reliable operation uses a Boolean parameter to set its reliable mode. If you set the parameter to False, then bmciiws_subscribe_reliable acts the same as the bmciiws_subscribe operation.

If your client sets the Reliable parameter to False, then the BMC II Web Services server stores events in the /log subdirectory under the name of the service. With a single-client connection, events are removed from the /log subdirectory after the BMC II Web Services server sends the events to the client.

Polling client (non-reliable subscription) If your client uses non-reliable subscription, then the BMC II Web Services Server stores events in the /log subdirectory under the name of the service.

Chapter 5


91

Polling client (non-reliable subscription)

When programming a client that receives events through non-reliable subscription and polling calls, invoke the following key operations in sequence: 1. bmciiws_subscribe_reliable (omit the callback URL parameter) You do not need to initiate a connection call (bmciiws_connect) to invoke subscription requests and receive events through polling. For polling calls, when you invoke the bmciiws_subscribe_reliable operation, you specify the selector name that matches the events you want to receive and the client context ID. However, you set the callback URL of the event listener server as an empty string (““) or as null. Set the Reliable parameter to False. When the BMC II Web Services server receives the subscription request without the callback URL, it automatically determines that it is a polling request. The BMC II Web Services server starts to build an event queue using the specified selector and client ID that it has received. The event queue resides on the server and buffers the events.

TIP Because each subscription request requires a specific selector name, you might first call the bmciiws_getFilterNames operation to identify the available selector names to which you can subscribe.

2. bmciiws_getEvents (the polling call) Invoke the bmciiws_getEvents operation to specify the polling parameters. In the request, the client specifies ■

the name of the selector as specified in the subscription call. The client is polling for events that match the selector criteria.

■

the client context ID (any string) that identifies the client making the polling request

■

a specified number of events that it wants to receive per polling call The num_of_events parameter acts as both an input and output parameter. As an input parameter, it indicates how many events the integration client wants to poll for in each bmciiws_getEvents call. The BMC II Web Services Server compares this integer with the value of the configuration parameter MaxReturnEventListSize (default value = 20). ■

92

If the num_of_events value is greater than the MaxReturnEventListSize parameter value, then either the MaxReturnEventListSize parameter value is returned or the remaining number of events in the event pool, if the number is less than the MaxReturnEventListSize.


Polling client (non-reliable subscription)

■

If the num_of_events value is less than the MaxReturnEventListSize parameter value, then the call returns up to but no more than the specified num_of_events value.

NOTE The number of requested events and the number of returned events can be two different values.

The example in the following figure shows an example of a bmciiws_getEvents_NO_INOUT operation, which returns a single structure and not two response elements. Otherwise, the operation works the same as the bmciiws_getEvents operation. bmciiws_getEvents_NO_INOUT(filterName, clientId, eventCount); bmciiws_getEvents_NO_INOUT(“Everything”, “321”, “20”);

In the response, the web services server retrieves the matching events from the event queue and forwards them in array format to the client. The server returns either the specified number of events or the number that it is able to retrieve from the queue. You can invoke multiple bmciiws_getEvents operations to retrieve all the available events. For each polling call per subscription, the client can specify a different number of events. 3. bmciiws_unsubscribe Invoke the bmciiws_unsubscribe to close the polling cycle and stop receiving events for this subscription request. When the client unsubscribes from a subscription, it sends the selector name and client context ID to the web services server. The subscription manager matches the selector name and context ID with the subscription and closes it. The program deletes the event queue from the server. All events in the $installDirectory/log or %installDirectory%\log subdirectory are removed. To poll for events matching a different selector name, create a separate subscription call with the specified selector and then invoke the polling call (bmciiws_getEvents) with the new selector.

TIP As a developer, you write the client code to handle the events. You can develop different polling scenarios. For example, you can invoke a polling call on a different thread to poll for different types of events.

Chapter 5


93

Polling client (reliable subscription)

Polling client (reliable subscription) 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 a cache directory (drive:\installDirectory\cache or installDirectory/cache). Use the reliable subscription operation to guarantee event delivery. The sequence is essentially the same as that of a non-reliable subscription, except that 1. the initial subscription call is bmciiws_subscribe_reliable with its reliable indicator set to True 2. the client must send an acknowledgement to the BMC II Web Services server in the form of the bmciiws_ack operation indicating that it has received the requested events. To implement reliable subscription in a polling interface, use these operations in sequence: 1. bmciiws_subscribe_reliable Set the Boolean parameter Reliable to True to indicate that your client is requesting guaranteed delivery. If you are uncertain about which selector to specify, you can call bmciiws_getFilterNames first to view the list of available selectors. 2. bmciiws_getEvents You can invoke multiple bmciiws_getEvents operations. For each bmciiws_getEvents request for which the client receives a response, you must call the bmciiws_ack operation to send an acknowledgement to the server. 3. bmciiws_ack After the client receives the events it requested in the bmciiws_getEvents operation, it calls the bmciiws_ack operation to send the acknowledgement to the server. The server removes the forwarded events from its %installDirectory%\cache or $installDirectory/cache subdirectory, but retains the control file for the subscription request. If the client does not send acknowledgments or stops polling, the cache subdirectory increases in size as the BMC II Web Services server continues to receive events.

94


Listener client (reliable or non-reliable subscription)

4. bmciiws_unsubscribe Call the bmciiws_unsubscribe operation to close the polling cycle and stop receiving events for this subscription request. All events in the %installDirectory%\cache or $installDirectory/cache subdirectory are removed, including the control file.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Server Reference Guide for descriptions of these polling operations.

Listener client (reliable or non-reliable subscription) Using a publish-subscribe interface, you can design a listener client that receives events through a custom event listener. The listener client registers a callback with its event listener. The callback implements an event handler. The client initiates a subscription request and sends it to the BMC II Web Services server. To implement a listener client, you will need to use the sample EventListener.wsdl. See Appendix C, “Sample Client Files” for more information.

TIP Just as a reminder, you can extend the operations in the EventListener.wsdl, but do not modify the declarations or definitions.

When programming a listener client, invoke the following key operations in sequence: 1. bmciiws_subscribe_reliable (include the callback URL parameter) You do not need to initiate a connection call (bmciiws_connect) to invoke subscription requests and receive events. When you invoke the bmciiws_subscribe operation, specify the ■ ■ ■ ■

selector name that matches the events you want to receive client context ID (any string) that identifies the client making the request callback URL of the event listener server that resides on the client Reliable parameter (True for reliable subscription, False for non-reliable)

Chapter 5


95

Using multiple subscription calls (bmciiws_subscribe_reliable)

TIP Because each subscription request requires a specific selector name, you might first call the

bmciiws_getFilterNames operation to identify the available selector names to which you can subscribe. When the WSCELL receives the event that matches the selector in the subscription request, it sends the event and client context ID to the event dispatcher of the BMC Impact Integration Web Services server. The event dispatcher dispatches the events to the event listener specified by the callback URL in the subscription request of the requesting client. The listener invokes the callback and calls the registered event handler function to consume the event. As a developer, you write the event handler logic to manage the event.

NOTE If your listener client uses a reliable subscription request, the events that the BMC II Web Services Server receives are stored in the %installDirectory%\cache or $installDirectory/cache subdirectory with a unique control file. Once received, the

events are automatically sent to the client based on the callback. (The listener client does not call the bmciiws_ack operation.) The events in the cache subdirectory are not removed, however. You can manually delete the contents of the cache subdirectory without unsubscribing from the request. 2. bmciiws_unsubscribe To stop receiving events, invoke the bmciiws_unsubscribe operation for this subscription request. If you are unsubscribing from a reliable subscription, all events in the cache subdirectory, including the control file, are removed.

Using multiple subscription calls (bmciiws_subscribe_reliable) Depending on the type of receive client you are building, you might want to invoke multiple subscription calls.

NOTE See the BMC Impact Integration Developer’s Kit Web Services Reference Guide for a description of the subscription operation, its parameters, and its messages.

The client that receives events can invoke one or both of two types of subscription calls depending on whether the client is using a publish-subscribe interface or a polling interface: 96


Using multiple subscription calls (bmciiws_subscribe_reliable)

■

In a publish-subscribe interface, the subscription contains the callback URL of its event listener server.

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable); bmciiws_subscribe_reliable (“Always matches”, “123”, “http://listener:7070/EventListener”, “False”); ■

In a polling interface, the callback URL is a null value.

bmciiws_subscribe_reliable (filterName, context, callback URL, Reliable); bmciiws_subscribe_reliable (“Always matches”, “123”, “”, “False”);

Multiple subscription calls must be unique to prevent the BMC II Web Services server from overwriting them. Each subscription call must have a unique combination of selector name and client context ID. Multiple subscriptions from a polling interface, from a publish-subscribe interface, or from a combined interface must be unique. The two following examples of subscription calls originate from a combined interface: bmciiws_subscribe_reliable (“Always matches_Major”, “123”, “http://listener:7070/EventListener”, “False”); bmciiws_subscribe_reliable (“Always matches_MINOR”, “123”, ““, “False”);

Each calls a different selector name (“Always matches_MAJOR” or “Always matches_MINOR”) but from the same client context ID (“123”). These are considered unique calls, and the BMC II Web Services server will not overwrite one with the other. Conversely, two subscription calls, each with a different client context ID, are considered unique even if they specify the same selector name. The following example shows two subscription calls originating from different client context IDs: one for a publish-subscribe interface and the other for a polling interface. bmciiws_subscribe_reliable (“Always matches”, “789”, “http://listener:7070/EventListener”, “False”); bmciiws_subscribe_reliable (“Always matches”, “123”, ““, “False”);

Although both calls specify the same selector (“Always matches”), they are unique calls because they contain different client context IDs (“789” and “123”). The BMC II Web Services server does not overwrite one with the other.

Chapter 5


97

Registering and receiving service component state change events

The following example shows two subscription calls—one for a publish-subscribe interface, the other for a polling interface—that are not unique. Each call specifies the same client context ID and calls the same selector name. bmciiws_subscribe_reliable (“Always matches”, “123”, “http://listener:7070/EventListener”, “False”); bmciiws_subscribe_reliable (“Always matches”, “123”, ““, “False”);

In this example, the BMC II Web Services server would overwrite the earlier subscription call with the later one.

Registering and receiving service component state change events Use the bmciiws_registerStateChange operation to register with a SIM cell to receive service component state change events. You do not need to add a Propagate rule or an event propagation policy just to receive state change events. The cell automatically sends the state change events to the WSCELL event listener specified in its mcell.dir file. A C declaration of the bmciiws_registerStateChange() function would look similar to the following example: string registrationID bmciiws_registerStateChange(string SIM_cell, string WSCELL_eventlistener, struct changeType); SIM_cell refers to the cell to which you are connecting and from which you are requesting the state change events. WSCELL_eventlistener refers to the value of the

WSCELL entry that specifies the BMC II Web Services Server which is registering with the cell to receive the events. changeType refers to one or more of the following service component change types that you want to receive: ■ ■ ■ ■ ■

bCompChange (component change) bCompDelete (component deletion) bRelChange (relationship change) bRelDelete (relationship deletion) bAll (component and relationship state changes)

The bmciiws_registerStateChange function() returns a registrationID from the BMC II Web Services Server that identifies and is associated with the request for state change events.

98


Workaround: multiple clients and state change events

Use the registrationID when you call the bmciiws_unregisterStateChange() function, an example declaration of which is shown below: bmciiws_unregisterStateChange(string SIM_cell,string registrationId);

Guidelines Make sure that the value of the serverName parameter of bmciiws_registerStateChange matches that of the Name value of the WSCELL entry in the mcell.dir file of the cell from which you are requesting the state change events. For example, the following code snippet is requesting that the SIM cell ABC send its state change events to the BMC II Web Services Server specified by the WSCELL entry myWSCELL: bmciiws_registerStateChange(“ABC”, myWSCELL, ...);

The mcell.dir file of the SIM cell should have a corresponding WSCELL entry for the requesting BMC II Web Services Server. cellABCMCmyIMComputer:1828 cellmyWSCELLMCmyWSComputer:19999

Workaround: multiple clients and state change events If in your environment, multiple clients are requesting state change events from the same SIM cell or cells, you must send your registration request by defining and sending a separate data message. Do not use the bmciiws_registerStateChange operation. When formulating your message, you specify values for the following slots in the SIM_NOTIFICATION_REGISTRY message class: Table 18

SIM_NOTIFICATION_REGISTRY message class: required slots (part 1 of 2)

Slot

Description

client_data

only applies to version 7 or later of BMC Service Impact Manager. Specifies a unique name for this registration call.

clients

denotes the value assigned to the WSCELL entry specifying the BMC II Web Services Server instance

Chapter 5


99

Workaround: multiple clients and state change events

Table 18

SIM_NOTIFICATION_REGISTRY message class: required slots (part 2 of 2)

Slot

Description

requested_notifications

indicates the type of service component state change that you want to receive. You can specify one or more of the following values: ■ ■ ■ ■

COMPONENT_CHANGE COMPONENT_DELETE RELATIONSHIP_CHANGE RELATIONSHIP_DELETE

notification_mode

indicates the notification mode

notifications_at_registration

Boolean indicate that says whether a notification is sent upon registration

asset_filters

a LIST_OF type that specifies the service components about which you want to receive state change events

The following example (generated from the .NET toolkit) shows how you can define the message: //create a registration for state change events /* * Create the data */ ::imapi::Event *event = new ::imapi::Event(); event->NameValue_element = new ::imapi::NameValueArray(1); event->NameValue_element->array[0] = new ::imapi::NameValue(); event->NameValue_element->array[0]->name = "client_data"; event->NameValue_element->array[0]->value = new ::imapi::Value(); event->NameValue_element->array[0]->value->what = ::imapi::Value::tString_value; event->NameValue_element->array[0]->value->string_value = "example_register"; event->NameValue_element->array[0]->value_type = ::imapi::DataType::STRING; event->NameValue_element->array[1] = new ::imapi::NameValue(); event->NameValue_element->array[1]->name = "clients"; event->NameValue_element->array[1]->value = new ::imapi::Value(); event->NameValue_element->array[1]->value->what = ::imapi::Value::tString_value; event->NameValue_element->array[1]->value->string_value = "[example_Server_name]"; event->NameValue_element->array[1]->value_type = ::imapi::DataType::STRING; //repeat the name-value definitions for each required slot

100


Implementing the Secure WASPC client

After you define the message, you send the registration as an event, an example of which is depicted in the following example: //send the registration WASP_VString id = test->impactManager->bmciiws_send(test>connection_id, event, 0,"SIM_NOTIFICATION_REGISTRY", ::imapi::IMMessageType::MSG_TYPE_NEW_DATA, ee);

Implementing the Secure WASPC client Use this procedure to ensure secure communication between the BMC II Web Services server and client.

1 Make sure that BMC II Web Services server is running with SSL configured as described in Chapter 4, “Securing web services.”

2 Using the OpenSSL source files, create ssleay32.* and libeay32.* libraries according to your platform, as follows: Platform

Files

Windows

ssleay32.dll and libeay32.dll

Solaris or Linux

ssleay32.so and libeay32.so

HP-UX

ssleay32.sl and libeay32.sl

AIX

ssleay32.lib and libeay32.lib or ssleay32.a and libeay32.a

See “Obtaining the OpenSSL source files” on page 67 for more information about downloading OpenSSL source files.

3 Copy the library files to installDirectory/bin, according to your platform. 4 Modify the installDirectory/conf/client.xml file to include secure transport xml by removing the line

5 Copy installDirectory/conf/openssl-http-client.xml to installDirectory/conf/transport_SSL.xml.

6 Modify installDirectory/conf/transport_SSL.xml by removing the line , as shown below:

remove line

WASPOpenSSL.dll libwasp_openssl.a libwasp_openssl.sl libwasp_openssl.so

102



openssl/certs

7 Save all your changes. 8 Start the BMC II Web Services Server if it not already running. 9 Run the client, substituting the secure server host name in the following URL: https://serverHost:6075/imapi

Chapter 5


103


104


Appendix

A

BMC Impact Integration Web Services Server Administration A

This appendix 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. The administrator should be familiar with the configuration files of BMC Impact Manager. This appendix describes the following topics: Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the BMC II Web Services Server reads selector files and parameters . . . . . . . Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the supplemental message selector files . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trace file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the trace configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the Integration mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix A


106 106 106 107 107 109 120 121 122 123 123 136 137 138 139 139

105

Starting server instances

Starting server instances The web services server administrator is responsible for starting and maintaining the server. To launch the server, follow the instructions in “Starting and stopping the BMC II Web Services Server” on page 59.

Selector file overview The BMC Impact Integration APIs use the selector file to define groups of criteria (called selectors) that are used to identify and select messages which propagate from BMC Impact Manager instances. Messages that match all the criteria in a selector become available to the BMC Impact Integration Web Services’ publish-subscribe and polling mechanisms. The selector file is a case-insensitive text file. The selector file is required for BMC Impact Integration Web Services’ clients that receive events from BMC Impact Manager instances.

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

A default selector file, iiws.selector, is stored under the mcell directory. Its file path is designated in the installDirectory/conf/servercfg.xml or drive:\installDirectory\conf \servercfg.xml file, as shown in the following example: svci:IIAPISelectorFile="C:\Program Files\BMC Software\Impact Integration Web Services/mcell/iiws.selector"

The BMC II Web Services Server loads this selector file automatically.

How the BMC II Web Services Server reads selector files and parameters The BMC II Web Services Server uses selectors to match incoming events and to make them available to subscribing clients.

106


Selector file description

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 that the servercfg.xml file specifies. (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 Whenever a client subscribes to multiple selectors, it runs the risk of receiving duplicate messages from a cell. The same message can satisfy the different criteria specified by each selector name and be forwarded to the subscribing client.

As BMC Impact Manager events propagate to the BMC II Web Services server, the server accesses the specified selector file, which is loaded in memory. When a BMC Impact Manager message matches a selector parameter in the selector file, the server looks into the subscription table to get the clients that have invoked subscriptions with the matching selector parameter name. The server dispatches the event to all web service clients that have subscribed to the selector parameter name.

NOTE When an incoming BMC Impact Manager event arrives, BMC II Web Services Server checks the event against all selectors in the selector set of the file. For each match of selector with event, it checks whether there is a subscription request from a subscribing web service client. It dispatches the event to each client that has a subscription with a matching selector entry.

Selector file description The following topics describe the structure and content of message selector set files as implemented by the BMC II Developer’s Kit.

Characteristics Message selector set files have the following characteristics: Appendix A


107

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.

■

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.

108

■

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.


Format

■

The message selector file supports the following comparison operators ■ ■ ■ ■

greater-than (>) greater-than or equal to (>=) less-than (

BMC Impact Integration Developer's Kit Web Services Server ...

BMC Impact Integration Developer's Kit Web Services Server ...

Suggest Documents

Zakat Kit

Should ruby developers care?

Should ruby developers care?

GainSpan TLS Web Server Application Development Kit

SitePlayer™ SPK1 Web Server Coprocessor Developer Kit

muslim integration

muslim integration

Media kit 2017

Media kit 2017

Aikido First Aid Kit

Oracle Application Server Web Services Developer's Guide

ArcGIS 10.3 Server on Amazon Web Services

WEB SERVICES WITH APPLICATION SERVER ABAP

TBR Server 2H16 CSAT

Intermedia's Cloud Server

Windows MultiPoint Server 2011

JasperReports Server Web Services Guide - Jaspersoft

Lenovo Server Chooser

TBR Server 2H16 CSAT

JasperReports Server Web Services Guide - Jaspersoft Community

Intermedia's Cloud Server

Windows Server 2016

WebSphere Portal Server and Web Services Whitepaper

Lenovo Server Chooser