BMC Impact Integration Developer s Kit Web Services Server Developer Guide

Transcription

1 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

2 Contacting BMC Software You can access the BMC Software website at 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 USA Outside United States and Canada Telephone or Telephone (01) Fax (01) Fax Copyright 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 , DFARS , DFARS , DFARS , and DFARS , as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX , USA. Any contract notices should be sent to this address.

3 Customer support You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or . 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 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 alerts when new product notices are released find worldwide BMC support center locations and contact information, including addresses, fax numbers, and telephone numbers Support by telephone or In the United States and Canada, if you need technical support and do not have access to the web, call or send an message to [email protected]. (In the subject line, enter SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance. Before contacting BMC Have the following information available so that Customer Support can begin working on your issue immediately: product information product name product version (release number) license number and password (trial or permanent) operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level sequence of events leading to the issue commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software 3

4 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 , or send an message to (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at , or send an message to (Asia-Pacific) Contact your BMC sales representative or your local BMC office. 4 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

5 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 Chapter 2 Installation 21 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 3 Configuration 37 Required configuration tasks How to synchronize BMC II Web Services Server and BMC IM cell connections.. 38 Troubleshooting tip: BMC II Web Services Server fails to reconnect Defining Propagate rules or event propagation policies for BMC IM cells Optional configuration tasks Configuring high availability cells for the BMC II Web Services Server Contents 5

6 Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment Updating default port numbers post installation Configuring Attributes in the BMC II Web Services Server Modifying the default BMC II Web Services Server log Starting and stopping the BMC II Web Services Server Microsoft Windows UNIX Connecting to BMC II Web Services Installing multiple instances of the BMC II Web Services Server When to assign a unique server instance name Administering the BMC II Web Services Server Chapter 4 Securing web services 65 Secure Sockets Layer (SSL) security Security implementation advisory Compatible OpenSSL toolkit Guidelines for implementing SSL Obtaining the OpenSSL source files About certificate generation Generating the BMC II Web Services Server certificate (Microsoft Windows) Generating the BMC II Web Services server certificate (UNIX or Linux) Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file Chapter 5 Guidelines for choosing client interfaces 73 Client components Programming language Available web services client features Guidelines for building a client interface Preparing the WSDL source-code generator Generating the client proxy code (client stubs) Systinet WASP Server for C ++ toolkit sample NET C# toolkit sample Apache Axis toolkit sample Using the NO_INOUT operations to return single elements for the Axis toolkit 78 Deciding which stub operations to use Compiling the client code Maximum number of open outgoing connections Implementing the send feature How a send request is processed Sequence of operations to use Implementing the query features How a query is processed Sequence of operations to use bmciiws_queryclassdefinitions: class definition array Implementing the receive feature Selector choices BMC Impact Integration Developer s Kit Web Services Server Developer Guide

7 Polling interface Publish-subscribe interface Reliable versus non-reliable subscription Polling client (non-reliable subscription) Polling client (reliable subscription) Listener client (reliable or non-reliable subscription) Using multiple subscription calls (bmciiws_subscribe_reliable) Registering and receiving service component state change events Workaround: multiple clients and state change events Implementing the Secure WASPC client 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 Appendix B Error Messages and Codes 141 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 Appendix C Sample Client Files 163 List of sample client files Event Listener Web Services Description Language (WSDL) file Event listener server Event dispatcher Namespaces Data types Messages Operations Contents 7

8 Bindings Service Listenercfg.xml file Adding SSL parameters to the listenercfg.xml file Index 175 Glossary BMC Impact Integration Developer s Kit Web Services Server Developer Guide

9 Figures Components of BMC Impact Integration Web Services mcell.dir example: BMC II Web Services Server mcell.dir example: BMC IM cell mcell.dir example: BMC II Web Services Server mcell.dir example: BMC IM cell Event propagation: many instances to one server Event propagation: many instances to many servers 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 HA implementation scenario for BPM and BMC II Web Services Server servercfg.xml file: default declaration Servercfg.xml with openssl parameters added and transport section removed Runtime directory folders for stub files bmciiws_queryclassdefinitions code sample Class definition array Structure of message selector set file Sample message selector set header Sample message selector set header Sample trace configuration file Dispatch Operations in EventListener.wsdl Figures 9

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

11 Tables Wasp library files Supported operating systems BMC IM support matrix Tested compilers Compatible toolkits UNIX distribution files Directory contents Required configuration tasks Location of mcell.dir Files mcell.dir configurations for queries mcell.dir configurations for sending events mcell.dir configurations for receiving events Optional configuration tasks Default port numbers Summary of Available Operations Components that support a receive interface Event selectors for subscription requests SIM_NOTIFICATION_REGISTRY message class: required slots Message selector set header contents Message selector header contents Message selector functions Message selector operators Keyword descriptions Supplemental message selector files Configuration file parameters BMC II C APIs Impact Integration Error Codes Core Communications Error Codes Sample client files: Systinet C++ queries Sample client files: Systinet C++ listener client Sample client files: Axis Java implementations Namespaces: EventListener.wsdl Message Parts: Dispatch_Request Message Parts: DispatchList_Request Tables 11

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

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

14 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

15 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

16 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: Event.xsd BasicTypes.xsd ImapiTypes.xsd 16 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

17 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

18 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 local mc localhost:1828 cell WSCELL mc :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 ) of the BMC II Web Services Server and listens for events on port number 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

19 Support overview Support overview You request the BMC Impact Integration Developer s Kit through the BMC Developer Network website at 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: 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 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

20 Intended audience for web services APIs 20 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

21 Chapter 2 Installation 2 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 21

22 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 Yes Yes Yes 22 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

23 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 Microsoft Visual C#.NET 2003 Apache Axis 1_3, Axis 1_4 OpenSSL OpenSSL OpenSSL compatibility The BMC II Web Services Server is compatible with version of OpenSSL. Chapter 2 Installation 23

24 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 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: Windows Linux Solaris HP-UX AIX 24 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

25 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

26 Installing the web services server package 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 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 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

27 Installing the web services server package 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 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

28 Installing the web services server package 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 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

29 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

30 Installation directory contents Table 7 Directory bin cache conf locale mcell openssl samples _uninst Directory contents Description 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. 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. contains XML configuration files including those for the BMC II Web Services Server, http server, and openssl components contains the language support message catalog files and the iiws.load file. Do not modify these files. 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 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. 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. 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

31 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

32 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

33 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

34 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

35 Uninstalling the web services server package 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 Uninstalling the web services server package 36 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

37 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 How to synchronize BMC II Web Services Server and BMC IM cell connections.. 38 Troubleshooting tip: BMC II Web Services Server fails to reconnect Defining Propagate rules or event propagation policies for BMC IM cells Optional configuration tasks Configuring high availability cells for the BMC II Web Services Server Configuring HA cells for BMC II Web Services Server in the BMC Performance Manager environment Updating default port numbers post installation Configuring Attributes in the BMC II Web Services Server Modifying the default BMC II Web Services Server log Starting and stopping the BMC II Web Services Server Microsoft Windows UNIX Connecting to BMC II Web Services Installing multiple instances of the BMC II Web Services Server When to assign a unique server instance name Administering the BMC II Web Services Server Chapter 3 Configuration 37

38 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 Defining Propagate rules or event propagation policies for BMC IM cells 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. To receive events (aside from state change events) from BMC IM cells, 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

39 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 Manager instance BMC Impact Integration Web 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: <Type> <Name> <EncryptionKey> <IPAddress:Port> cell cella MC myimcomputer:1828 cell cellb MC myimcomputer1:1828 cell cellc MC myimcomputer2:1828 cell celld MC 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. Chapter 3 Configuration 39

40 How to synchronize BMC II Web Services Server and BMC IM cell connections 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 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 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 mcell.dir example: BMC II Web Services Server <Type> <Name> <EncryptionKey> <IPAddress:Port> cell WSCELL MC mywscomputer:19999 cell cellconnect MC myimcomputer:1828 cell cellconnect 1 MC secondimcomputer:1828 cell cellconnect 2 MC 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 Sending events mcell.dir example: BMC IM cell <Type> <Name> <EncryptionKey> <IPAddress:Port> cell cellconnect MC myimcomputer:1828 cell cellconnect 1 MC secondimcomputer:1828 cell cellconnect 2 MC thirdimcomputer:1828 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 mcell.dir entries: BMC II Web Services Server instance To send events 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 40 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

41 How to synchronize BMC II Web Services Server and BMC IM cell connections 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 mcell.dir example: BMC II Web Services Server <Type> <Name> <EncryptionKey> <IPAddress:Port> cell WSCELL MC mywscomputer:19999 cell cellconnect MC myimcomputer:1828 cell cellconnect 1 MC secondimcomputer:1828 cell cellconnect 2 MC thirdimcomputer:1828 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. Chapter 3 Configuration 41

42 How to synchronize BMC II Web Services Server and BMC IM cell connections Figure 5 mcell.dir example: BMC IM cell <Type> <Name> <EncryptionKey> <IPAddress:Port> cell WSCELL MC mywscomputer:19999 cell cellconnect MC myimcomputer:1828 cell cellconnect 1 MC secondimcomputer:1828 cell cellconnect 2 MC thirdimcomputer:1828 If your BMC II Web Services Server implementation serves multiple purposes, one of which is receiving events, then follow the mcell.dir examples for receiving events. 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. <Type> <Name> <EncryptionKey> <IPAddress:Port> cell cellconnect MC myimcomputer:1828 cell WSCELL MC mywscomputer: 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

43 How to synchronize BMC II Web Services Server and BMC IM cell connections For example, if the server instances are on different systems, you can make the WSCELL entries as shown in the following figure: <Type> <Name> <EncryptionKey> <IPAddress:Port> cell cellconnect MC myimcomputer:1828 cell WSCELL MC mywscomputer:19999 cell WSCELL1 MC secondwscomputer:19999 cell WSCELL2 MC 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: <Type> <Name> <EncryptionKey> <IPAddress:Port> cell cellconnect MC myimcomputer:1828 cell WSCELL MC mywscomputer:19999 cell WSCELL1 MC mywscomputer:20000 cell WSCELL2 MC 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. Chapter 3 Configuration 43

44 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: <Type> <Name> <EncryptionKey> <IPAddress:Port> cell WSCELL MC :19999 cell cellconnect MC myimcomputer:1828 cell cellconnect1 MC myimcomputer1:1828 cell cellconnect2 MC myimcomputer2:1828 cell cellconnect3 MC myimcomputer3:1828 Guidelines Do not change the local host IP address of 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 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 44 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

45 Defining Propagate rules or event propagation policies for BMC IM cells 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. Chapter 3 Configuration 45

46 Defining Propagate rules or event propagation policies for BMC IM cells 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

47 Defining Propagate rules or event propagation policies for BMC IM cells 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.) Chapter 3 Configuration 47

48 Defining Propagate rules or event propagation policies for BMC IM cells 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

49 Defining Propagate rules or event propagation policies for BMC IM cells 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 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. Chapter 3 Configuration 49

50 Defining Propagate rules or event propagation policies for BMC IM cells 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

51 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 Configuring high availability cells for BMC II Web Services Server in the BPM environment Updating default port numbers post installation Configuring attributes in the BMC II Web Services Server Default logging You can configure two cells so that one acts as a secondary server to the primary one in case the primary server fails. In this way, the BMC II Web Services Server can communicate with a secondary cell server until the primary one returns online. You can configure an HA pair to accommodate a primary and a backup web services server in the BMC Performance Manager (BPM) environment. You can update these port numbers after installation if a port number conflict develops. 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. This topic describes the different log files that the BMC II Web Services Server uses 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. Chapter 3 Configuration 51

52 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

53 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. Chapter 3 Configuration 53

54 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

55 Updating default port numbers post installation 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 Component HTTP transport server WSCELL Default port numbers File Windows: drive:\installdirectory\conf\ servercfg.xml Solaris, Linux, HP-UX, AIX: installdirectory/conf/servercfg.xml Windows: drive:\installdirectory\mcell\mcell.dir Solaris, Linux, HP-UX, AIX: installdirectory/mcell/mcell.dir Default Port Number Chapter 3 Configuration 55

56 Updating default port numbers post installation 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 <waspc-config xmlns:wasp= urn:waspserver xmlns:cppa= urn:cppadaptor xmlns:sep= urn:serviceendpoint xmlns:svci= urn:serviceinstancerepository xmlns:trans= urn:transportrepository > <wasp:import ref= serverbase.xml /> <trans:transport trans:class= WASP_HTTPTransportServer trans:scheme= server-http xmlns:hts= urn:httptransportserver hts:reusecount= 15 hts:reusetimeout= 30 hts:rwtimeout= 30 hts:accepttimeout= 5 hts:chunked= true hts:port= 6070 hts:hostname= $AUTO$ hts:dispatcher= DefaultDispatcher hts:singlethread= 0 hts:maxsparethreads= -1 hts:maxthreads= -1 /> <!--For enabling SSL communication, copy contents of servercfg.security.xml here. --> <sep:serviceendpoint sep:dispatcherref= DefaultDispatcher sep:adaptorref= DefaultCppAdaptor cappa:wsdl= /installdirectory/bin/impactmanager.wsdl sep:url= /imapi > <cppa:additionalwsdl cppa:url= BasicTypes.xsd cppa:location= BasicTypes.xsd /> <cppa:additionalwsdl cppa:url= Event.xsd cppa:location= Event.xsd /> <cppa:additionalwsdl cppa:url= ImapiTypes.xsd cppa:location= ImapiTypes.xsd /> <cppa:instance cppa:ref= imapi /> </sep:serviceendpoint> 56 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

57 Configuring Attributes in the BMC II Web Services Server <svci:serviceinstance svci:name= imapi svci:class= IMWSimpl svci:maxreturneventlistsize= 30 svci:iiapiconfigfile= /installdirectory/mcell/iiws.conf svci:iiapiselectorfile= /installdirectory/mcell/ iiws.selector svci:iiwsinstancename= IIWS_Server svci:messagelistenercellname= WSCELL svci:servercachedir= /installdirectory/cache </waspc-config> 2 In the trans:transport element tag, change the value of the hts:port attribute to an available port number. 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. To Change the Port Number of the WSCELL event listener 1 In a text editor, open the mcell.dir file located under drive:\installdirectory\mcell or installdirectory/mcell. 2 Change the port number. 3 Save and close the mcell.dir 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. Configuring Attributes in the BMC II Web Services Server You can configure the MaxResponseEventListSize attribute of a BMC II Web Services Server. This attribute defines the web service instance in the servercfg.xml file. The MaxResponseEventListSize attribute is an absolute value of type int. It defines the maximum number of events that the server returns per polling request. This value can be different from the number of events that the client requests. The default value is 30. The recommended range of values is 20 to 100. Update the attribute in the BMC II Web Services Server by changing the value in the servercfg.xml file. Chapter 3 Configuration 57

58 Modifying the default BMC II Web Services Server log To update attributes in the servercfg.xml File 1 Open the drive:\installdirectory\conf\servercfg.xml file or installdirectory/conf/servercfg.xml file in a text editor. Refer to Figure 11 on page Using the information in this section as a guide, modify the attribute values. 3 Save 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. Modifying the default BMC II Web Services Server log By default, the BMC II Web Services Server uses the installdirectory/mcell/trace.log or drive:\installdirectory\mcell\trace.log to record its activities. A BMC II Web Services Server administrator can modify the trace.log parameters such as log file name and directory location in the iiws.conf file found under installdirectory/mcell/ drive:\installdirectory\mcell\ The administrator can change the default logging level in the iiws.trace file also found under the same directory path. To modify the default log parameters 1 In a text editor, open the iiws.conf file. The trace parameters are contained in the following stanza, depicted in the following example: Trace=Yes TraceSrc=No TraceConfigFileName=iiws.trace LocaleConfigFileName=C:\Program Files\BMC\IIWS/locale/iiws.load TraceDefaultFileName=trace.log TraceFileSize= TraceFileHistory=1 TraceFileAppend=No 2 Modify the configuration parameters. Refer to Configuration file parameters on page 123 for a description of the configuration parameters. Skip to Step 5 if you are done with your changes. 3 To change the level of logging detail, open the iiws.trace file. You can modify the default values, which are depicted in the following example: 58 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

59 Starting and stopping the BMC II Web Services Server ALL ALL stderr ALL VERBOSE no 4 Modify the file according to the instructions in the BMC Impact Solutions: General Administration guide. You can refer also to Editing the trace configuration file on page 138 for more information. 5 Restart the BMC II Web Services Server to initialize the changes. NOTE The BMC II Web Services Server temporarily keeps client-requested events in the drive:\installdirectory\log or installdirectory/log subdirectory for non-reliable subscriptions and in the drive:\installdirectory\cache or installdirectory/cache subdirectory for reliable subscriptions. The events remain in the log or cache folders until the client consumes them or the client unsubscribes from the server. Starting and stopping the BMC II Web Services Server This section describes how to start and stop the BMC II Web Services Server automatically as a service or daemon process. It also describes how to start the server in a Command Prompt window under Windows and in a terminal window under UNIX. Before you begin Ensure that you have updated your system variables as described in Setting environment variables under Microsoft Windows on page 31 and Setting environment variables under Solaris, Linux, HP-UX, and AIX on page 32. Verify that any BMC Impact Manager instances that you want to connect to are entered in the BMC II Web Services Server s mcell.dir file under drive:\installdirectory\mcell or installdirectory/mcell the BMC II Web Services Server s WSCELL entry has been added to the mcell.dir file under drive:\installdirectory\etc or installdirectory/etc of each BMC Impact Manager installation from which you want to receive events Chapter 3 Configuration 59

60 Microsoft Windows Microsoft Windows On Windows computers, if you install the BMC II Web Services Server as a service, the service is started automatically when the installation is complete. You can stop and restart the service through the Windows Control Panel. Under Services, locate the BMC II Web Services Server process name (iiws_iiws, by default) in the list, rightclick to open the pop-up menu, and choose the appropriate command. If you do not install the BMC II Web Services Server as a service, you will need to start the server manually in the Command Prompt window. The startup command requires that you specify only one parameter, the location of the server configuration file (servercfg.xml). You launch this server startup command from the \bin subdirectory of the installation directory: for example, drive:\installdirectory\bin. To start the BMC II Web Services Server manually (Microsoft Windows) 1 In a Command Prompt window, change directory to drive:\installdirectory\bin. 2 Enter the following command string: imserv -console drive:\installdirectory\conf\servercfg.xml NOTE imserv is the name of the constant that defines the BMC II Web Services Server executable file. 3 Leave the Command Prompt window open while the server is running. The output documents the events, which match the selector criteria, that the BMC II Web Services Server receives from the BMC Impact Manager instance. 4 Issue the kill interrupt of the DOS shell to shut down the server. In Windows, it can be Ctrl+C. UNIX On UNIX platforms, if you install the BMC II Web Services Server as a daemon, the daemon startup script, IIWSServer, automatically sets the appropriate environment variables. The IIWSServer script is created in the /bin subdirectory (installdirectory/bin). 60 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

61 UNIX To start the server using the script Depending on how you installed the BMC II Web Services Server package, you can start the server daemon under a local account or as root. In either case, you enter the following command from the /bin subdirectory:./iiwsserver start If you have defined the installdirectory/bin path in the $PATH variable, you (or the administrator) can start the server daemon by entering IIWSServer start. The absolute path command is installdirectory/bin/iiwsserver start. Enter an IIWSServer stop command in a new terminal window to shut down the server gracefully. (The $LD_LIBRARY_PATH variable must be set.)./iiwsserver stop To start the server using the executable If you do not install the BMC II Web Services Server as a daemon, you can start the server as a daemon process or a console process. In either case, the startup commands require that you specify only two parameters: the name that you want to give the process the location of the server configuration file (servercfg.xml) 1 Change directory to the /bin subdirectory (installdirectory/bin). cd installdirectory/bin 2 Enter the following command to start the server as a daemon process:./imserv -start nameofdaemonprocess installdirectory/conf/servercfg.xml Or you enter this command to start the server as a console process:./imserv -console installdirectory/conf/servercfg.xml 3 Leave the terminal window open while the server is running. 4 To stop the service, enter Ctrl + C on the terminal window. Alternatively, you can retrieve the list of running processes using the ps -ef command, and then enter the kill command against the server s PID to terminate the process. Chapter 3 Configuration 61

62 Connecting to BMC II Web Services Connecting to BMC II Web Services After you start the BMC II Web Services Server, you can connect to BMC II Web Services at the service endpoint, as defined by the URL where hostnameofserver identifies where the web services server instance is installed, portnumber identifies the HTTP port (the default is 6070), imapi is the name defined for this web service (you can define your own). Installing multiple instances of the BMC II Web Services Server Depending on your deployment strategy and performance loads, you may want to install and run multiple instances of the BMC II Web Services Server service on the same system or on different systems. For example, you can connect each service instance to different clients and BMC Impact Manager instances. A client can subscribe to different event types by connecting to different BMC II Web Services Servers. To install another instance of the BMC II Web Services Server service, repeat the installation sequence that is appropriate for the platform. If you are installing an service instance on a different system, you can accept the default service name and port number values that the installation routine provides. If you are installing an instance on the same system, follow these guidelines during the installation: Assign a unique name to the service. Ensure that each service instance is assigned unique port numbers. If a cell is sending events to multiple service instances, assign a unique WSCELL name to each instance in the cell s mcell.dir file. Refer to How to synchronize BMC II Web Services Server and BMC IM cell connections on page 38 for more information. 62 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

63 When to assign a unique server instance name When to assign a unique server instance name NOTE The service instance name and the server instance name are distinct values. You define the service instance name or choose its default value as you are installing the BMC II Web Services Server. After you install the server, it is automatically assigned the default server instance name IIWS_Server. You can change this configuration value by modifying the IIWSInstanceName configuration parameter in the servercfg.xml file. When multiple servers have registered with the same cell to receive state change events, you must assign a unique server instance name to each server. To assign a unique server instance name 1 In a text editor, open the servercfg.xml file located under drive:\installdirectory\conf or installdirectory/conf. See Updating default port numbers post installation on page 55 for an example servercfg.xml file. 2 In the svci:iiwsinstancename element tag, change the default entry to a unique value. For example, you can change it from svci:iiwsinstancename="iiws_server" svci:messagelistenercellname="wscell" to svci:iiwsinstancename="iiws_server_1" svci:messagelistenercellname="wscell_1" 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 To enable the server instance to receive events, make the appropriate WSCELL entry in the mcell.dir file of the cell that is sending events. See How to synchronize BMC II Web Services Server and BMC IM cell connections on page 38 for more information. Chapter 3 Configuration 63

64 Administering the BMC II Web Services Server NOTE If the server instance is receiving state change events only, you do not need to add a Propagate rule or an event propagation policy. If it is to receive other events in addition to state change events, then you must add a corresponding Propagate rule or an event propagation policy to the KB of the sending cell. See Defining Propagate rules or event propagation policies for BMC IM cells on page 45 for the procedure. Administering the BMC II Web Services Server Administering the BMC II Web Services Server consists of typical server administration tasks and two tasks unique to the BMC II Web Services implementation: managing the selector file (iiws.selector) and the configuration file (iiws.conf). The Web Services server reads both files at startup. Both files are stored under drive:\installdirectory\mcell or installdirectory/mcell. The selector file is crucial in determining which events the subscribing clients receive. When you are first setting up and practicing with the BMC II Web Services Server toolkit, you do not need to modify the default iiws.selector file. You can issue subscription requests that include the selector name Always matches for the $ClassName Event. Using this selector, your client receives all events propagating from the BMC Impact Manager instances. Later, as you define your client more carefully, you will probably want to modify the selector file. The iiws.conf is preconfigured so that you do not have to modify the iiws.conf to run the BMC II Web Services Server. Later, as you learn more about your integration needs, you can modify the parameters in the configuration file. Modifying the selector file is a task best performed by a BMC II Web Services Server administrator who has administered the BMC Impact Manager product. The same administrator can also manage the configuration file, updating the parameters as required. The mcell directory also contains four supplemental selector files. You can enable one or more of these files to improve the speed and efficiency of event filtering between the BMC II Web Services Server and the cell. These selector files do their processing in the background and, unlike the iiws.selector file, are not loaded by the BMC II Web Services Server at startup. For more information about the.selector and.conf files, see Appendix A, BMC Impact Integration Web Services Server Administration. 64 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

65 Chapter 4 Securing web services 4 This chapter presents guidelines on how to implement secure sockets layer (SSL) security on the BMC II Web Services Server. It is addressed to developers or security administrators who are knowledgeable about secure sockets layer (SSL) implementations. This chapter describes the following topics: Secure Sockets Layer (SSL) security Security implementation advisory Compatible OpenSSL toolkit Guidelines for implementing SSL Obtaining the OpenSSL source files About certificate generation Generating the BMC II Web Services Server certificate (Microsoft Windows).. 68 Generating the BMC II Web Services server certificate (UNIX or Linux) Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file Secure Sockets Layer (SSL) security HyperText Transport Protocol (Secure) or HTTPS is a secure transport protocol layer. HTTPS is basically a secure version of HTTP that is implemented over a secure sockets layer (SSL) encrypted session. You use for HTTP URLs over SSL. SSL encryption, which underlies HTTPS transport, relies on an exchange of trusted certificates between the sender and the receiver. In this case, the web services server and the client exchange certificates that guarantee the server and the client are who they say they are. Chapter 4 Securing web services 65

66 Security implementation advisory The BMC II Web Services server supports HTTPS on all supported operating systems: Microsoft Windows Linux Solaris HP-UX AIX The BMC II Web Services server is not preconfigured with SSL. You can implement SSL on the supported operating systems by using the open source toolkit available through the OpenSSL Project at The toolkit enables you to generate your certificates in PEM (privacy enhanced mail) format. Security implementation advisory Although the BMC II Web Services Server supports certain client security plug-in modules, it does not provide these modules in its package distribution. BMC does not guarantee that all versions of publicly available security modules are compatible with the BMC II Web Services Server. Security implementation is the responsibility of the client developer. BMC Software assumes no responsibility for any losses or damages that may result. Compatible OpenSSL toolkit The BMC II Web Services Server package is compatible with version of the OpenSSL toolkit. Guidelines for implementing SSL These guidelines summarize the main tasks of implementing SSL security. Ensure that your BMC II Web Services client understands HTTPS transport. For secure communication between the BMC II Web Services client and server in a development or testing environment, you should generate a self-signed public key and a self-signed private key using the generateopensslservercer.bat file or generateopensslservercert.sh script in this BMC II Web Services Server package. 66 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

67 Obtaining the OpenSSL source files For information about generating the keys, see Generating the BMC II Web Services Server certificate (Microsoft Windows) on page 68 or Generating the BMC II Web Services server certificate (UNIX or Linux) on page 69. Self-signed private keys are not recommended for production environments. For secure communication in a production environment, you should obtain a signed certificate from a certificate authority. To obtain a specific certificate signed by a certificate authority for BMC II Web Services Server, generate a certificate signing request (CSR) and private key for the host system where the BMC II Web Services server resides. To generate these keys, you can download the open source toolkit available through the OpenSSL Project at When generating your CSR, remember to specify the correct common name for the server. The common name can be the host and domain name, or if the certificate is to used in an internal network, it can be one word or the name of the server. Store the private key in a server directory that contains trusted certificates. Send the CSR to the certificate authority to obtain the trusted public key certification. You can send your CSR to a certificate authority in an . When you receive the certificate, store it in an appropriate directory on the BMC II Web Services server. Enter the SSL parameters in the servercfg.xml file under %installdirectory%\conf or $installdirectory/conf. See Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file on page 70 for more information. Make the trusted public key certificate available to clients through the BMC II Web Services connection during a secure SSL connection session. The client automatically stores the public key certificate for BMC II Web Services in a certificate directory. This certificate contains information that the client can verify, so it can trust the identity of the host to which it has connected. The certificate can also allow a client to send encrypted data to the server, data that only the server can decrypt. If you generate your own certificate, unsigned by any certificate authority, for the BMC II Web Services server, then any client that wishes to make a secure communication must import the unsigned certificate into its directory of trusted certificates. Obtaining the OpenSSL source files You can go to to download the appropriate distribution file. Extract the source files from the distribution file using the appropriate utility. Next, follow the instructions included in the download package on how to compile and generate the appropriate library files for your platform. Chapter 4 Securing web services 67

68 About certificate generation Add the OpenSSL drive:\installdirectory\bin or installdirectory/bin to your PATH variable. UNIX and Linux users should add the OpenSSL installdirectory/lib directory to the $LD_LIBRARY_PATH variable. About certificate generation The generateopensslservercer.bat file or generateopensslservercert.sh script in this BMC II Web Services Server package generates a self-signed certificate that you can use for development and testing. To accommodate a production environment, you should obtain a signed certificate from a certificate authority. For information on generating a certificate request and submitting it to a certificate authority, you can go to Generating the BMC II Web Services Server certificate (Microsoft Windows) 1 Copy the following OpenSSL library file drive:\opensslinstalldirectory\perl\5.8\net_ssleay\blib\arch\auto\net\ssleay\ssleay.dll to the drive:\installdirectory\bin directory of the BMC II Web Services Server. 2 Open a Command Prompt window, and run the BMC II Web Services Server %OpenSSLinstallDirectory%\openssl\generateOpenSSLServerCert.bat file. This batch file generates a 1024 bit RSA private key and stores it in BMC II Web Services Server %installdirectory%\openssl\server-key.pem. It generates a server certificate and stores it under the %installdirectory%\openssl\certs directory path. NOTE If you receive any error messages, such as unable to write random state, report them to your developer or OpenSSL expert. Your server certificate has probably not been created. 3 Update the drive:\installdirectory\conf\servercfg.xml file with the contents of the servercfg.security.xml file. See Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file on page 70 for more information. 68 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

69 Generating the BMC II Web Services server certificate (UNIX or Linux) NOTE You may need to copy the server certificate to the client system. Generating the BMC II Web Services server certificate (UNIX or Linux) 1 Ensure that you have execute permission on the $installdirectory/share/waspc/openssl/generateopensslservercert.sh script file. If needed, run the chmod command from the appropriate directory, as in chmod 755 generateopensslservercert.sh 2 Run the generateopensslservercert.sh script to generate the BMC II Web Services server certificate. This script generates a 1024 bit RSA private key and stores it in BMC II Web Services Server $installdirectory/share/waspc/openssl/server-key.pem. It generates a server certificate and stores it under the $installdirectory/share/waspc/openssl/certs directory path. 3 Update the $installdirectory/conf/servercfg.xml file with the contents of the servercfg.security.xml file. See Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file on page 70 for more information. NOTE You may need to copy the server certificate to the client system. Chapter 4 Securing web services 69

70 Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file After you obtain the server certificate, you need to instruct the BMC II Web Services server how to authenticate the certificate. You configure the BMC II Web Services server to use HTTPS transport by adding security parameters to the %installdirectory%\conf\servercfg.xml or $installdirectory/conf/servercfg.xml file. These security parameters are copied from either of these files: %installdirectory%\conf\servercfg.security.xml $installdirectory/conf/servercfg.security.xml Once you copy the parameters, you must remove the transport section from the servercfg.xml file. To replace nonsecure parameters with secure SSL parameters 1 Open the servercfg.xml file and the servercfg.security.xml file. 2 Copy the code contents of the servercfg.security.xml file and insert them into the servercfg.xml file just after the comment line that says <!--For enabling SSL communication, copy contents of servercfg.security.xml here. -->. 3 Remove the following transport section from the servercfg.xml file: <trans:transport trans:class= WASP_HTTPTransportServer trans:scheme= server-http xmlns:hts= urn:httptransportserver hts:reusecount= 15 hts:reusetimeout= 30 hts:rwtimeout= 30 hts:accepttimeout= 5 hts:chunked= true hts:port= 6070 hts:hostname= $AUTO$ hts:dispatcher= DefaultDispatcher hts:singlethread= 0 hts:maxsparethreads= -1 hts:maxthreads= -1 /> 4 Save the servercfg.xml file. 5 Restart the BMC II Web Services server. See Starting and stopping the BMC II Web Services Server on page BMC Impact Integration Developer s Kit Web Services Server Developer Guide

71 Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file Contents from servercfg.security.xml file 6 To verify that you can connect to the BMC II Web Services server in secure mode, open a browser and enter the following https URL: 7 Click Yes in the Security Alert window. You should see the ImpactManager.wsdl displayed. Figure 12 is an example of a Windows-based servercfg.xml file after the contents of the servercfg.security.xml file have been copied into it and the transport section removed. The section shown in boldface text is the contents of the servercfg.security.xml file. The example also uses the default server port number for a secure HTTPS connection, which is The library file WASPOpenSSL.dll, referenced in this example, is for a Windows implementation. The library file libwasp_openssl.so is for Linux and Solaris implementations Figure 12 Servercfg.xml with openssl parameters added and transport section removed <waspc-config xmlns:wasp= urn:waspserver xmlns:cppa= urn:cppadaptor xmlns:sep= urn:serviceendpoint xmlns:svci= urn:serviceinstancerepository xmlns:trans= urn:transportrepository > <wasp:import ref= serverbase.xml /> <!--For enabling SSL communication, copy contents of servercfg.security.xml here. --> <wasp:externallibrary> <!-- Windows --> <wasp:path>waspopenssl.dll</wasp:path> <wasp:debugpath>waspopenssldbg.dll</wasp:debugpath> </wasp:externallibrary> <trans:transport xmlns:hts="urn:httptransportserver" xmlns:htssl="urn:httpsopenssltransportserver" trans:class="wasp_httpsopenssltransportserver" trans:scheme="server-https-openssl" hts:reusecount="1" hts:reusetimeout="30" hts:rwtimeout="30" hts:accepttimeout="5" hts:chunked="true" hts:port="6075" hts:hostname="$auto$" hts:dispatcher="defaultdispatcher" hts:singlethread="0" hts:maxsparethreads="-1" > <!-- Client verification enabled. Note that this causes problems with Web browsers! --> <htssl:context htssl:class="wasp_opensslcontextfactoryimpl" Chapter 4 Securing web services 71

72 Replacing nonsecure transport parameters with SSL parameters in the servercfg.xml file xmlns:ssl="urn:opensslcontextfactory" ssl:certificatefile="openssl/server-cert.pem" ssl:privatekeyfile="openssl/server-key.pem" ssl:privatekeypasswordfile="openssl/server-pass.txt" ssl:verify="no" > <ssl:trusteddir>openssl/certs</ssl:trusteddir> </htssl:context> </trans:transport> <sep:serviceendpoint sep:dispatcherref= DefaultDispatcher sep:adaptorref= DefaultCppAdaptor cappa:wsdl= /installdirectory/bin/impactmanager.wsdl sep:url= /imapi > <cppa:additionalwsdl cppa:url= BasicTypes.xsd cppa:location= BasicTypes.xsd /> <cppa:additionalwsdl cppa:url= Event.xsd cppa:location= Event.xsd /> <cppa:additionalwsdl cppa:url= ImapiTypes.xsd cppa:location= ImapiTypes.xsd /> <cppa:instance cppa:ref= imapi /> </sep:serviceendpoint> <svci:serviceinstance svci:name= imapi svci:class= IMWSimpl svci:maxreturneventlistsize= 30 svci:iiapiconfigfile= /installdirectory/mcell/iiws.conf svci:iiapiselectorfile= /installdirectory/mcell/ iiws.selector svci:iiwsinstancename= IIWS_Server svci:messagelistenercellname= WSCELL svci:servercachedir= /installdirectory/cache </waspc-config> 72 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

73 Chapter 5 Guidelines for choosing client 5 interfaces This chapter describes guidelines for choosing a web services client interface that is compatible with the BMC II Web Services server. BMC neither supports nor endorses a particular client interface. This chapter describes the following topics: Client components Programming language Available web services client features Guidelines for building a client interface Preparing the WSDL source-code generator Generating the client proxy code (client stubs) Systinet WASP Server for C ++ toolkit sample NET C# toolkit sample Apache Axis toolkit sample Using the NO_INOUT operations to return single elements for the Axis toolkit 78 Deciding which stub operations to use Compiling the client code Maximum number of open outgoing connections Implementing the send feature How a send request is processed Sequence of operations to use Implementing the query features How a query is processed Sequence of operations to use bmciiws_queryclassdefinitions: class definition array Implementing the receive feature Selector choices Polling interface Publish-subscribe interface Reliable versus non-reliable subscription Polling client (non-reliable subscription) Polling client (reliable subscription) Listener client (reliable or non-reliable subscription) Using multiple subscription calls (bmciiws_subscribe_reliable) Chapter 5 Guidelines for choosing client interfaces 73

74 Client components Registering and receiving service component state change events Workaround: multiple clients and state change events Implementing the Secure WASPC client Client components When you build a client interface, you use these components: the client source code that you generate using the WSDL code generator the customized client code that you write Programming language You can use any programming language that is supported by web services and your toolkit of choice. Available web services client features Using the BMC Impact Integration Web Services APIs, you can program your web services client to send events and data query class definitions in the SIM IM cell query service model component information stored in the SIM IM cell query service model component impacts and their root cause query dynamic data in the cell query events receive events through a polling or publish-subscribe interface 74 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

75 Guidelines for building a client interface Guidelines for building a client interface This section describes the steps that you must perform to build a web services client that is compatible with the BMC II Web Services server. 1. Determine that the type of client that you want to create: 2. Supply the path name of the ImpactManager.wsdl document to your toolkit s WSDL source-code generator. 3. Using your toolkit s WSDL source-code generator, compile the ImpactManager.wsdl document into the target source code, generating the source and header files of the client proxy code (client stubs) as a result. 4. Using the generated client proxy code as a basis, decide which functions to use in your client code. 5. Write the custom code for the selected client features. 6. Test the client. Preparing the WSDL source-code generator You must supply the path name of the ImpactManager.wsdl file to your toolkit s source-code generator. The ImpactManager.wsdl is located by default under the %installdirectory%\bin or $installdirectory/bin directory. If the BMC II Web Services server is running, you can also open a browser and specify the Impact Integration Web Services URL: for example, number/imapi/. (The default port number is 6070.) The exact name and location of your WSDL source-code generator depends on your web services toolkit. Generating the client proxy code (client stubs) To obtain the client proxy code, compile the ImpactManager.wsdl using your toolkit s WSDL source-code generator. Depending on your toolkit, you can run the sourcecode generator in its home directory or the directory of your choice. Some examples from different toolkits follow. You can find the sample code under the %installationdirectory%\samples or $installationdirectory/samples directory path. You can also refer to Appendix C, Sample Client Files, for additional information. Chapter 5 Guidelines for choosing client interfaces 75

76 Systinet WASP Server for C ++ toolkit sample Systinet WASP Server for C ++ toolkit sample Using the source-code generator in the Systinet WASP Server for C++ toolkit, you can enter a command string similar to the following: C:\WASP-CPP-4.6-win-VC60-bin\bin>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: 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 76 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

77 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: 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 Guidelines for choosing client interfaces 77

78 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

79 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 bmciiws_getcellinfo bmciiws_connect bmciiws_send bmciiws_getfilternames bmciiws_subscribe bmciiws_subscribe_reliable bmciiws_ack bmciiws_getevents bmciiws_unsubscribe bmciiws_disconnect bmciiws_queryevents bmciiws_querydata bmciiws_queryeventbyid bmciiws_querydatabyid bmciiws_queryeventsbydate Description to identify BMC Impact Manager instances that are connected to the BMC Impact Integration Web Services Server to connect to a specified BMC Impact Manager instance to send a client event or data object to the specified BMC Impact Manager instance to retrieve the available selector names to which the client can 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. 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. 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. to request a specified number of events matching a defined event selector for a particular client. Used in polling calls to unsubscribe from the specified event selector in the BMC Impact Manager instance to disconnect from the BMC Impact Manager instance to query a specific BMC Impact Manager instance for events to query a specific BMC Impact Manager instance for data to query a specific BMC Impact Manager instance for events matching a specified BMC Impact Manager event ID to query a specific BMC Impact Manager instance for data objects matching a specified BMC Impact Manager data ID 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 Guidelines for choosing client interfaces 79

80 Deciding which stub operations to use Table 15 Summary of Available Operations (part 2 of 2) Operation bmciiws_querycomponent bmciiws_querycomponentsbystatus bmciiws_querycomponentstatus bmciiws_querycomponentevents bmciiws_querycomponentsby Condition bmciiws_querymodelimpact bmciiws_querypossiblerootcause bmciiws_queryclassdefinitions bmciiws_getqueryresultcount bmciiws_getqueryresult bmciiws_endquery bmciiws_setmaintenancemode bmciiws_setmanualstatus bmciiws_registerstatechange bmciiws_unregisterstatechange Description to query a specified component object to retrieve its component data attributes to query service components that MC_SM_COMPONENT_STATUS values in the specified range and which belong to the specified base class or subclass 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 to query service components for direct and impact events. You have the option of retrieving only impact events. 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. to query for possible consumer components of the specified component ID to query for a component or components that are the possible root cause of a specified component s status 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 to obtain the total number of events or data objects that have been returned by the query to obtain a specified number of events or data objects to satisfy the query to end the query cycle and disconnect from the specified BMC Impact Manager instance to request to place a specified component in maintenance mode to request to set a designated manual status on the specified component to register your client with a BMC SIM cell to receive state change events 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

81 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 Guidelines for choosing client interfaces 81

82 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

83 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 Guidelines for choosing client interfaces 83

84 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

85 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 Guidelines for choosing client interfaces 85

86 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 imname querymode baseclase classname classonly Value testcmdb 0 (indicates that the BMCII_DATA_CLASSES are being queried) BMC_AssetBase blank 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

87 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:: 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 Guidelines for choosing client interfaces 87

88 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

89 Selector choices Table 16 Component WSCELL Components that support a receive interface Propagate rules or event propagation policies Description 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 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. Subscription requests Selectors 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. 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 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 Selector name Always matches Modifies Everything Event selectors for subscription requests Description allows you to receive (filters in) all new events from the specified BMC IM cell allows you to receive only modified events from the cell 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 Guidelines for choosing client interfaces 89

90 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: 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 90 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

91 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, 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 Guidelines for choosing client interfaces 91

92 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). 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. 92 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

93 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 Guidelines for choosing client interfaces 93

94 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

95 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 Guidelines for choosing client interfaces 95

96 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

97 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, 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, 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, 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 Guidelines for choosing client interfaces 97

98 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, 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

99 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. <Type><Name><EncryptionKey><IPAddress:Port> 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 client_data clients Description only applies to version 7 or later of BMC Service Impact Manager. Specifies a unique name for this registration call. denotes the value assigned to the WSCELL entry specifying the BMC II Web Services Server instance Chapter 5 Guidelines for choosing client interfaces 99

100 Workaround: multiple clients and state change events Table 18 SIM_NOTIFICATION_REGISTRY message class: required slots (part 2 of 2) Slot requested_notifications notification_mode notifications_at_registration asset_filters Description 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 indicates the notification mode Boolean indicate that says whether a notification is sent upon registration 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

101 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 Windows Solaris or Linux HP-UX AIX Files ssleay32.dll and libeay32.dll ssleay32.so and libeay32.so ssleay32.sl and libeay32.sl 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 <wasp:import ref="transport.xml and adding the line <wasp:import ref="transport_ssl.xml"/> as shown below: <?xml version="1.0"?> <waspc-config xmlns:scr="urn:stubconfigrepository" xmlns:wasp="urn:waspserver"> <wasp:import ref="transport.xml remove line <wasp:import ref="transport_ssl.xml"/> add line <wasp:import ref="transcoder.xml"/> Chapter 5 Guidelines for choosing client interfaces 101

102 Implementing the Secure WASPC client <wasp:import ref="soapprotocol.xml"/> <wasp:import ref="header.xml"/> <wasp:import ref="serialization.xml"/> <wasp:import ref="deleter.xml"/> <wasp:import ref="interceptor.xml"/> <!-- Client config module --> <wasp:module wasp:class="wasp_stubconfigrepositoryimpl"/> <!-- Asynchrony handler --> <wasp:module wasp:class="wasp_separatethreadasyncreceipthandlermodule"/> <!-- Default client configuration --> <scr:stubconfig xmlns:scec="urn:stubconfigentrycontent" scec:xmlprotocolhandler="soap" scec:xmlprotocoldirectoutput="1" scec:outputxmlencoding="utf-8" scec:interceptor="dimeinterceptor" /> </waspc-config> 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 <wasp:import ref="openssllib.xml"/>, as shown below: <?xml version="1.0"?> <waspc-config xmlns:trans="urn:transportrepository" xmlns:wasp="urn:waspserver"> <wasp:import ref="openssllib.xml"/> remove line <!-- Module TransportRepository --> <wasp:module wasp:class="wasp_transportrepositoryimpl"/> <trans:transport trans:class="wasp_filetransportclient" trans:scheme="file" xmlns:ftc="urn:filetransportclient" ftc:extout=".out" /> <wasp:externallibrary> <! Add line based on your operating system > <!-- Windows --> <wasp:path>waspopenssl.dll</wasp:path> <! AIX > <wasp:path>libwasp_openssl.a</wasp:path> <! HP > <wasp:path>libwasp_openssl.sl</wasp:path> <! Linux or Solaris > <wasp:path>libwasp_openssl.so</wasp:path> </wasp:externallibrary> 102 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

103 Implementing the Secure WASPC client <trans:transport xmlns:htc="urn:httptransportclient" xmlns:htcssl="urn:httpsopenssltransportclient" trans:class="wasp_httpsopenssltransportclient" trans:scheme="https" htc:retrycount="10" htc:retrytime="100" htc:reusecount="100" htc:reusetimeout="30" htc:rwtimeout="30" htc:conntimeout="30" htc:http10="false" htc:chunked="false" > <htcssl:context htcssl:class="wasp_opensslcontextfactoryimpl" xmlns:ssl="urn:opensslcontextfactory" ssl:verify="yes"> <ssl:trusteddir><insert proper location>openssl/certs</ssl:trusteddir> </htcssl:context> </trans:transport> </waspc-config> 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: Chapter 5 Guidelines for choosing client interfaces 103

104 Implementing the Secure WASPC client 104 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

105 Appendix A BMC Impact Integration Web A Services Server Administration 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 BMC Impact Integration Web Services Server Administration 105

106 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 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

107 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 BMC Impact Integration Web Services Server Administration 107

108 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. 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. 108 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

109 Format The message selector file supports the following comparison operators greater-than (>) greater-than or equal to (>=) less-than (<) less-than or equal to (<=) The message selector file supports these comparison operators for numerals only. The message selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname= EVENT. The message selector file supports required slots. A required slot keyword determines the required slot or slots in the message selector criteria. The message must have the specific required slot for it to match the message selector criteria. The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you add as a prefix to the specific slot name: for example, reqdslot.msg= TEXT. To illustrate, if the message selector criteria specified that the slot msg is required (reqdslot.msg= TEXT ), then a message that did not have the slot msg would fail the matching test. The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the message selector criteria. When the FailOnMissingSlot parameter is set equal to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the message selector criteria. You can use the full range of regular expressions as values for message selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at runtime. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library. Format Figure 16 on page 110 depicts the structure of the message selector set file. Appendix A BMC Impact Integration Web Services Server Administration 109

110 Format Figure 16 Structure of message selector set file Message selector set files must contain header information that describes the message selector set. The header information consists of message selector set headers, described in Message selector set header on page 110 message selector headers, described in Message selector header on page 111 Message selector criteria are described in Message selector criteria on page 113. Message selector set header The message selector set header provides the entire set of message selectors in the file with identifying information and indicates whether the message selector set is enabled for use. A single message selector set header must precede all message selectors and their selector groups in the message selector set. Table 19 on page 111 describes the required and optional message selector set header parameters that precede the message selectors in a set. 110 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

111 Format Table 19 Message selector set header contents Parameter Description Inclusion SelectorSetName= name of the message selector set Required FormatVersion= Version= ChangeDate= Description= Enable= Note: The SelectorSetName can be seen in the Trace file. Use this functionality to debug problems with a specific message selector set. minimum version of the BMC II Web Services Server required to run the message selector using this file version number of the message selector set file, specified manually by the developer or integration end-user date when the file last changed, specified manually by the developer or integration end-user free-text description of the entire message selector set specifies whether the message selector set (and all message selectors in it) are enabled for use Valid values: Optional Optional Optional Optional Required TRUE enabled FALSE disabled Figure 17 Sample message selector set header SelectorSetName=testselector FormatVersion=2 Version=7.1 ChangeDate=November 14, 2007 Description=This file contains the event selector tests Enable=TRUE Message selector header A message selector header provides each set of message selector criteria in the file with identifying information indicates how some message selector features will be implemented indicates whether the specific message selector criteria, including any message selector groups included within it, are enabled for use Appendix A BMC Impact Integration Web Services Server Administration 111

112 Format A message selector header must precede each collection of message selector criteria in the message selector set. Table 20 on page 112 describes the required and optional message selector header parameters that precede each message selector. Table 20 Message selector header contents Parameter Description Inclusion SelectorName= name of the message selector, used by the BMC II Web Services Server to identify the message selector that will be used in selection Required The name must be unique within the message selector set. Description= free-text description of the message selector Optional FailOnMissingSlot= indicates whether the match for the message selector fails if a slot specified in the message selector criteria is missing from the message Optional Valid values: TRUE the match for the message selector fails if a slot specified in the message selector is missing from the message FALSE missing slots cause the line to be ignored IsSubSelector Enable= If the message that is being examined does not include any of the slots that are being tested by the message selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false. If you use the reqdslot keyword in the message selector criteria, it is in effect only when FailOnMissingSlot is set equal to false. Indicates whether the message selector can be called only by the $doselector() function. Valid values are true or false. specifies whether the message selector is enabled for use Valid values: Optional Required TRUE enabled FALSE disabled 112 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

113 Format Figure 18 Message selector criteria Each message selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in Table 22 on page 117. Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated). In addition, the message selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR,, or && connector. Format issues Sample message selector set header SelectorName=EVENT_SELECTOR Description=Selectors for all events of class EVENT FailOnMissingSlot=false IsSubSelector=true Enable=TRUE Messages selector functions, which are internal to the message selector file, are described in Table 21 on page 114. Operators are described in Table 22 on page 117. Each message selector in a set is enclosed in curly braces ({ }). Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep. To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function. Explicit text that is used as a matching criterion must be enclosed in double-quotes (" "). If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match. The message selector functions scan each successive selector group in a message selector until it finds a match. Once they find a match, they stop searching. The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter message selector functions, as well as conceal developer comments. When a line in a message selector is commented out, the selection function ignores it. Appendix A BMC Impact Integration Web Services Server Administration 113

114 Format Do not comment out whole message selectors or selector sets. Instead, set the Enable parameter of the message selector set header or the message selector header to FALSE to disable the message selector set or selector. EXAMPLE The $functionname resolves a specified function and compares the results of that operation to a slot in the message: for example, $ClassName = "SECURITY_ALERT" The $ClassName function returns the class name of the message. The returned value is compared to the value to the right of the operator (in this case, the class name, SECURITY_ALERT). If the message class name is SECURITY_ALERT, then the test is successful. Table 21 Message selector functions (part 1 of 4) Function $HostName $ClassName Description specifies the host name of the computer on which the message selection program is running: for example, $HostName="MYCOMPUTER". This function can also be inserted in the new message as a slot value: for example, "MYCOMPUTER"=$HostName.. class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event. Examples: slot.slotname slot.imclass=$classname $ClassName="EVENT" compares the value of slot.slotname in the message with the value specified to the right of the operator. When the slot and the value are both present in the message, the criterion is considered a match. Example: slot.severity = Critical 114 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

115 Format Table 21 Message selector functions (part 2 of 4) Function $doselector Description calls additional message selectors or subselectors, either or both of which can be linked to or included with an overarching message selector $doselector is used as a single criterion in the message selector or subselector. $ClassName!="EVENTS" $doselector(security_sel) slot.status!= "OPEN" The message selector examines the message class to determine whether it is EVENTS. Then, the message is compared to the security_sel selector. If that comparison is completed successfully (all criteria matching), the comparison process continues processing using the original message selector. Example of $doselector calling a subselector: SelectorName=SELECTOR_ONE Description=does some quick checks then calls the sub selector FailOnMissingSlot=false Enable=TRUE { slot.host="bob" $doselector(selector_sub) } SelectorName=SELECTOR_SUB Description=makes sure it is not a test event FailOnMissingSlot=false Enable=TRUE { slot.msg!="this is a test" $Class!="EVENT" } $slotpresent Note: For a message to be considered a match to a message selector, it must match all the criteria of the message selector, including the criteria of message selectors or subselectors called by the $doselector function. specifies a slot name that must appear in the message that is being examined for the criterion to be a match Example: $SlotPresent(slot.severity) Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered. Appendix A BMC Impact Integration Web Services Server Administration 115

116 Format Table 21 Message selector functions (part 3 of 4) Function $slotmissing Description specifies a slot name that must not appear in the message that is being examined for the criterion to be a match Example: $SlotPresent(slot.severity) $TimeT Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered. returns the number of seconds since January 1, 1970 in number format. Examples: $Format mc_date=$timet Slot.mc_date=$TimeT similar to printf, uses %s to insert values into a string, expands \t and \n. Note: %s is the only formatter available for $format. Examples: $LocalTime mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port) $format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin. enables you to specify the local time using the same format parameters as strftime Examples: $GmtTime time=localtime("%i:%m:s%p") Slot.time=LocalTime("%I:%M:S%p") enables you to specify GMT time using the same format as strftime Examples: $substring time=$gmttime("%i:%m:s%p) Slot.time=$GmtTime("%I:%M:S%p") extracts specified components of a string Example: msg=$substring(slot.test, 0, 20) $ToLower $ToUpper where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include. converts all of the characters in a string to lowercase Example: mc_host=$tolower(slot.hostname) converts all of the characters in a string to upper case Example: mc_domain=$toupper(slot.domain) 116 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

117 Format Table 21 Message selector functions (part 4 of 4) Function $GetListValue Description retrieves the value at a specified location in a slot list Example: note=getlistvalue(slot.notes, 3) $IpFromName $HostFromIp where the first parameter (slot.notes in the example) is the slot to be examined from the source message and the second parameter (3) is the index of the value to be retrieved. performs a domain name server (DNS) lookup for the host name associated with the specified IP address Example: IP=$IpFromName("hostname.domain") performs a DNS lookup for the IP address associated with the specified host name Example: mc_host=$hostfromip(slot.srcip) Table 22 on page 117 describes the operators that can be used for comparison in a message selector set file. Table 22 Message selector operators (part 1 of 3) Operators Description = for a match, the result to the left of the equals ( = ) operator must equal the result to the right of the operator Example: $Slot.Test = EVENTS!= for a match, the result to the left of the not equals (!= ) operator must not equal the result to the right of the operator Example: $ClassName!="EVENT" =~ regular expression operator If the message that is being evaluated by the message selector contains the specified parameter and parameter value, a match is made. Example: slot.severity=~"maj*." The message selector file supports multiple regular expression operators and keywords. Appendix A BMC Impact Integration Web Services Server Administration 117

118 Format Table 22 Message selector operators (part 2 of 3) Operators Description!=~ regular expression operator If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails. Example: OR slot.severity!=~"maj~." symbol and literal string, both of which specify an OR relationship between successive lines of message selector criteria or between successive message selector groups Example: OR relationship between successive lines of criteria $HostName = data301 $HostName = data400 && AND By default, AND relationships exist between successive lines of message selector criteria. symbol and literal string, both of which specify an AND relationship between successive lines of message selector criteria or between successive message selector groups Example: AND relationship between message selector groups { slot.test= EVENTS slot.mc_host= EVENTS } AND { slot.test= EVENTS2 slot.mc_host= EVENTS2 } By default, AND relationships exist between successive lines of message selector criteria. 118 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

119 Format Table 22 Message selector operators (part 3 of 3) Operators Description { } indicates groups of alternate message selector criteria within an inidividual message selector. A group can be nested one level deep. Example: { { slot.test= EVENTS slot.mc_host= EVENTS } AND { slot.test= EVENTS2 slot.mc_host= EVENTS2 } } > specifies a greater-than comparison. Used exclusively with numerical relationships Example: slot.test>10 >= specifies a greater-than or equal to comparison. Used exclusively with numerical relationships Example: slot.test>=11 < specifies a less-than comparison. Used exclusively with numerical relationships Example: slot.test<12 <= specifies a less-than or equal to comparison. Used exclusively with numerical relationships Example: slot.text<=11 Table 23 on page 120 describes message selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name. Appendix A BMC Impact Integration Web Services Server Administration 119

120 Editing the selector file Table 23 Keyword metaslot. reqdslot. slot. Keyword descriptions Description designates a slot as a metaslot, which means a slot that provides information about the message. The keyword, followed by a dot, is prefixed to the slot name that it designates. Example: metaslot.class_name="event" designates a slot as a required slot. If the FailOnMissingSlot parameter is set equal to FALSE and if the message does not contain the specified required slot, it will not pass the message selector criteria. If the FailOnMissingSlot parameter is set equal to TRUE, then the BMC II C APIs ignore the reqdslot indicator. Example: reqdslot.msg="test" designates a readable slot value in regular expressions slot.msg=~"event from slot.host" The BMC II C APIs return the value of host before forwarding the regular expression to the expression library. NOTE For additional information about selector files, see the BMC Impact Integration Developer s Kit C API Developer Guide. Editing the selector file 1 If necessary, copy the iiws.selector file from the drive:\installdirectory\mcell or installdirectory/mcell directory to the working directory of your BMC II Web Services Server installation. 2 In a text editor, open the iiws.selector. 3 Modify the different file components selector set header, selector header, selector content, and operators as needed. 4 Save the file using the file name of your choice and the file extension.selector. If you change the name of the selector file, modify the server instance parameter svci:iiapiselectorfile in the servercfg.xml file accordingly. 5 Ensure that the selector file can be read by the user under whose permissions the web services server is running. 120 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

121 Supplemental message selector files 6 If the BMC II Web Services server is running, restart it to initialize the changes. See Starting and stopping the BMC II Web Services Server on page 59. Supplemental message selector files The BMC II Developer s Kit C API loads these four supplemental message selector files, each serving a different filtering purpose for incoming and outgoing events: recvfilterin.selector recvfilterout.selector sendfilterin.selector sendfilterout.selector On the BMC II Web Services Server side, these supplemental message selector files are stored under %installdirectory%\mcell or $installdirectory/mcell. By default, the filters contained in these files are turned off (Enable=FALSE). When you enable them and define the selectors, they are used in conjunction with the iiws.selector file to help filter events in or out. All incoming and outgoing events that are sent or received by the BMC II Web Services Server are first scanned by the filters in these message selector files. These filters are global, applying to all events that are passed back and forth between the BMC II Web Services Server and the cell. If the incoming events are not rejected by the supplemental message selector files, then they are scanned by the filters in the BMC II Web Services Server s iiws.selector file, which is specific to the client request. Table 24 on page 121 describes in more detail the different message selector files. Table 24 Supplemental message selector files Direction Message selector file Description Incoming events recvfilterin.selector recvfilterout.selector specifies the message selector criteria for accepting incoming events. If the incoming event does not match the message selector criteria, it is rejected automatically. specifies the message selector criteria for rejecting incoming messages. If the incoming event does not match the message selector criteria, it is passed on to be scanned by the message selector criteria in the integration s selector file. Appendix A BMC Impact Integration Web Services Server Administration 121

122 Editing the supplemental message selector files Table 24 Outgoing events Supplemental message selector files Direction Message selector file Description sendfilterin.selector sendfilterout.selector specifies the message selector criteria for approving and passing on outgoing events. If the outgoing event does not match the message selector criteria, it is filtered out automatically. specifies the message selector criteria for rejecting outgoing events. If the outgoing event does not match the message selector criteria, it is passed to its destination. Editing the supplemental message selector files 1 To enable any of the message selector files, open it in a text editor. The example below shows an excerpt from the recvfilterin.selector file: ## Selector Set information SelectorSetName=RECV_FILTER_IN Version=1 FormatVersion=2 ChangeDate=October 18, 2005 Description=This file contains selectors for filtering in incoming events Enable=FALSE SelectorName=BY_CLASS Data= Description=This example will filter in based on class. FailOnMissingSlot=false Enable=FALSE { $ClassName="EVENT" } 2 For each selector set and each selector you wish to use, change the Enable parameter from FALSE to TRUE. You can modify the selector criteria of each selector to accommodate your filtering requirements. TIP Be sure to keep the selector criteria in the supplemental selector files consistent with the selector criteria that is defined in the iiws.selector file. You do not want to accidentally filter out events that your integration client wants to receive. 3 Save the modified selector file; do not change the file name. 122 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

123 Configuration file 4 If the BMC II Web Services server is running, restart it to initialize the changes. See Starting and stopping the BMC II Web Services Server on page 59. Configuration file The BMC II Web Services configuration file, iiws.conf, is a text file. The configuration file is stored in the drive:\installdirectory\mcell or installdirectory/mcell directory that resides on the BMC II Web Services Server. It is accessed at runtime by the BMC II Web Services server. 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:iiapiconfigfile="c:\program Files\BMC Software\Impact Integration Web Services\mcell\iiws.conf" You can create several configuration files. You decide which one to load on the server to make available to the web service clients. The configuration file contains parameters that: specify whether the tracing facility is used, where the trace parameters file is located, where the sample log file that is created is located, and how that log file is maintained determine how underlying BMC II C APIs operate are required by your web services server NOTE It may be convenient for you to store additional parameters required by your web services server in the *.conf file. This is optional. co If you choose to do this, your web services server accesses these parameter values using the configuration functions described in the BMC Impact Integration Developer s Kit C API Developer Guide. Configuration file parameters Table 25 on page 124 lists and describes the configuration file parameters as implemented by the BMC II APIs. Appendix A BMC Impact Integration Web Services Server Administration 123

124 Configuration file parameters The default iiws.conf contains a subset of these values, plus a unique configuration parameter value, DisableSlotListSet, which should always be set equal to Yes. This configuration parameter value enables the BMC II Web Services Server to process incoming messages that are enclosed within brackets as regular slot strings. Table 25 Configuration file parameters (part 1 of 12) Group Parameter Description Impact Manager Instances ServerDirectoryName path and name of the directory file (default file name: mcell.dir). Required. BMC Software recommends that you store the mcell.dir file in the integration working directory or in the $MCELL_HOME/etc directory. Notes: ServerLocation The mcell.dir file contains a list of all BMC Impact Manager instances to which the integration can connect. The integration can use the mcell.dir file supplied with the integration, or it can use the mcell.dir file of a BMC Impact Manager instance that is already installed on the same host. specifies an individual IP address or host name that the server binds to 124 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

125 Configuration file parameters Table 25 Configuration file parameters (part 2 of 12) Group Parameter Description Connection Manager ClientSourceIP ClientSourcePort ConnectionSetupTimeOut static IP address that your integration can use when it is acting as a client (sending events). Optional. port that your integration can use when it is acting as a client (sending events). Optional. maximum time, in seconds, that a CLI command attempts to establish a connection to a cell If the connection with the cell cannot be completely established within this time frame, the command aborts. Default: 10 seconds Notes: If the cell is busy with a database cleanup, it may be impossible to connect the CLI with the default values. A database cleanup has a duration limit defined by the EventDBCleanupDurationLimit option, with a default value of 30 seconds. With a default ConnectionSetupTimeOut of 10 seconds, the connection cannot be established within the first 20 seconds of a cleanup. EventDBCleanupDurationLimit is described in the BMC Impact Solutions: General Administration guide. Appendix A BMC Impact Integration Web Services Server Administration 125

126 Configuration file parameters Table 25 Configuration file parameters (part 3 of 12) Group Parameter Description Connection Manager (continued) ConnectionPortRange specifies the range of ports to use for outgoing connections For a cell, this applies to forward propagation. It is the port used on the client side (or on the propagating cell side). This is useful only to pass the event through firewalls with high restrictions. Most firewall configurations ignore source port information but require destination port information. However, firewall configuration usually can restrict the source ports as well. ConnectionPortReuse The default is (empty). indicates whether or not the ports specified in ConnectionPortRange should be reused as much as possible By default, the cell or CLI tries to reuse ports from the specified range, in the given order. When ConnectionPortReuse=No, for every new connection within the same session, the next free port from the specified range is used. Only when it reaches the end of the range will it restart at the beginning of the range. Encryption Default=Yes indicates whether communications are encrypted Message Propagation MessageBufferKeepSent MessageBufferKeepWait MessageBufferSize Valid values: No Yes (Default) time, in seconds, to keep sent messages buffered while waiting for an answer Default: 300 seconds time, in seconds, that messages are retained in the buffer while waiting for the connection to be established Default: 3600 seconds (one hour) maximum number of messages that can be stored in the message buffer. Optional. Default: 2000 messages 126 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

127 Configuration file parameters Table 25 Configuration file parameters (part 4 of 12) Group Parameter Description Message Propagation (continued) MessageBufferReconnectInterval period of time, in seconds, between attempts to connect to a BMC Impact Manager instance. Optional. Default: 600 seconds Notes: The value of this parameter cannot be less than 60 seconds. When a connection is established, the integration sends buffered messages that are designated for the BMC Impact Manager instance with which the connection is established. MessageBufferResendCount For more information, refer to the BMC Impact Integration Developer s Kit C API Developer Guide. number of times to resend unanswered messages Default: 1 Appendix A BMC Impact Integration Web Services Server Administration 127

128 Configuration file parameters Table 25 Configuration file parameters (part 5 of 12) Group Parameter Description Persistency Buffer Manager PersistencyEnabled enables persistency, which specifies additional buffering parameters when the buffer mode is Default Valid values: PersistencyLevel No (Default) Yes buffer mode used when the Default buffering mode is specified. This parameter is enabled only when the PersistencyEnabled parameter value is Yes. Optional. Valid values: None (Default) Low High PersistencyFileName PersistencyCleanupSize Threshold PersistencyCleanupGarbage Threshold PersistencyDisconnectRemoves Messages Note: These values are case-sensitive and should be entered as shown here. name of the file in which the buffered messages are stored Default: log_directory\imgwintegrationname.dat [persist.dat] threshold size, in bytes, of the persistency file that activates garbage collection threshold size, as a percentage of file size, of the persistency file that activates garbage collection The default is 40 percent. indicates whether messages written to the persistency file are deleted when the integration disconnects intentionally from a BMC Impact Manager instance Valid values: No (Default value) Yes Note: The contents of the file are not deleted when the integration terminates unexpectedly. 128 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

129 Configuration file parameters Table 25 Configuration file parameters (part 6 of 12) Group Parameter Description Heartbeats HeartBeatInterval integer that indicates the number of seconds between heartbeats. Default value: 30 seconds EnableHeartBeats The minimum value is 1 second. The configuration file does not define a maximum value. a Boolean indicator that determines whether the integration component uses the heartbeat signal. Valid values are true/false yes/no The entries are not case sensitive. Receive buffer KeepRecvPersisted Boolean indicator that determines whether a message file persists when the associated message is removed from the message queue Valid values are true/false yes/no The entries are not case sensitive. The default value is true or yes, indicating that the persistent file that contains a copy of the message remains after the message is removed from the queue. ReceiveBufferDir EnableRecvPersist When the integration is running in server mode and receives an incoming message (an event or a modify), it saves a copy of the message to a file. By default, the integration does not delete the message file until the integration calls the bmcii_freemessage() function. If you set the KeepRecvPersisted parameter value to false or no, the integration deletes the message file when the message is removed from the queue. the directory where receive buffer resides. The default is the log_directory Boolean indicator that shows whether the message file persists in the incoming buffer. The default is false, meaning that the message file is not persisted in the incoming buffer. Appendix A BMC Impact Integration Web Services Server Administration 129

130 Configuration file parameters Table 25 Configuration file parameters (part 7 of 12) Group Parameter Description Receive buffer (continued) DropAcks Boolean indicator (true/false, yes/no) that tells the receive buffer to retain or drop acknowledgments. The default is true. When the DropAcks is set to true, the integration application does not receive replies indicating that the request is a success. However, the integration application still receives cancellation notices and error messages. RecvBufferSize Do not modify the default setting because the BMC II Web Services Server does not need to process acknowledgments. It operates more efficiently by not processing them. number value that restricts the number of events acknowledgements error messages cancellation notifications status notifications connection notifications that are stored in their respective buffers and that are received from a cell (propagation), an mposter command, or another integration. Note: These items are stored in two separate buffers. The RecvBufferSize value applies to each one. Events and modifies are stored in one buffer, while the acknowledgements, error messages, and notifications are stored in a second buffer. The default value is 20,000. When the default or specified maximum value is reached in each buffer, the buffer discards the oldest item and begins to cycle the items as new ones are received. If you set the value to 0, then no restriction is placed on the size of either buffer. 130 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

131 Configuration file parameters Table 25 Configuration file parameters (part 8 of 12) Group Parameter Description Trace Parameters Trace flag that indicates whether tracing is enabled. Optional. Valid values: YES or ON enable tracing TraceSrc NO or OFF disable tracing (Default) when displaying a trace message, specifies whether to display the source code file name and line number where trace message originated. Optional. Valid values: YES or ON display file name and line number NO or OFF no display of file name and line number TraceTime Note: Depending on the location of the trace message, the source may be in the integration or the BMC II Web Services Server code. Boolean indicator that says whether the date and time are appended to the trace file. The default value is YES. Valid values are YES or ON date and time are appended to the trace value TraceConfigFileName TraceDefaultFileName NO or OFF date and time are not appended path and file name for the iiws.trace file. Required, if Trace=YES. You can enter a hard-coded file path or use the substitution parameters described in Editing the configuration file on page 136. default destination file (trace.log) to which trace messages are redirected from stderr, when the integration runs as a daemon or a service. Required, if Trace=YES. Appendix A BMC Impact Integration Web Services Server Administration 131

132 Configuration file parameters Table 25 Configuration file parameters (part 9 of 12) Group Parameter Description Trace Parameters (continued) TraceFileSize maximum size, in KB, of the trace messages file. Optional. Valid values: 0 - No limit n - size of file in KB TraceFileHistory Note: BMC Software recommends that the value of this parameter be no less than 500 KB. number of trace files to be kept in history. Each file numbered sequentially. Optional. Valid values: 0 No files kept. (Default) TraceFileAppend n - number of files to keep when the integration is restarted, specifies whether to append new trace messages to the existing message trace file. Optional. Valid values: YES or ON appends new messages to the existing trace message file (Default) NO or OFF - empties the current trace message file 132 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

133 Configuration file parameters Table 25 Configuration file parameters (part 10 of 12) Group Parameter Description Troubleshooting UseMemWatch Boolean indicator that activates a debug behaviors which determines whether the integration is passing bad data to the BMC II C APIs Valid values are true/false yes/no The default value is false or no. If you enable the UseMemWatch parameter, the BMC II C APIs maintain a list of valid memory that contains strings, string lists, messages, and replies. Any memory objects that the BMC II C APIs create and pass back to the integration are tracked and verified. You can view any errors in the integration s trace log. The memory list created by the BMC II C APIs does not validate string values that are created by an integration. DumpIncoming Boolean indicator that tells the integration whether to add incoming events to the trace file. The default is false. Performance MinClientSleep For an integration that is defined as a client, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing. The valid values are 0 to 2000 milliseconds under Windows 1 to 2000 milliseconds on UNIX platforms The default value is ten milliseconds on both platforms. Note: If your client sends a large number of events in a continuous stream, you can consider increasing the MinClientSleep value so that the client can use more time to send events and the BMC IM cell can keep pace with the event processing. Appendix A BMC Impact Integration Web Services Server Administration 133

134 Configuration file parameters Table 25 Configuration file parameters (part 11 of 12) Group Parameter Description Performance (continued) MinSleep For an integration that is in server mode, this is a string value that determines the absolute minimum time for which the receive thread pauses during its processing. The valid values are MaxSleep MinQueryTimeout 0 to 2000 milliseconds under Windows; default value is 0 1 to 2000 milliseconds on UNIX platforms; default value is 1 string value that determines the upper range of the receive thread s pause time The valid values range from any value greater than the MinClientSleep or MinSleep value to 2000 milliseconds. The default value is 500 milliseconds. integer that specifies the absolute minimum time in milliseconds that the integration waits for a query result before it times out. The timeout period measures the time between responses from the cell. The default value is 2000 milliseconds (2 seconds). For example, your query call requests 100 results. You receive the first 50 results without a delay equal to or greater than 2 seconds. However, you do not receive the next result within two seconds. Your integration then times out. You can override this configuration parameter value in the query function bmcii_retrievequeryresults by specifying a timeout value greater than the minimum specified by the MinQueryTimeout parameter. If the value is the same or lower, it is ignored. 134 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

135 Configuration file parameters Table 25 Configuration file parameters (part 12 of 12) Group Parameter Description Miscellaneous UniqueIDFile overrides the default name and/or location of the uniqueid.dat file. Optional. Notes: The default location is the workingdir/log/instance_name/uniqueid.dat. The location and name of this file can be overridden. To use this parameter, the integration must have permission to write to the uniqueid.dat file. ServerAllInterfaces The value of this parameter in this file increments by one (1) before a new ID is assigned. specifies whether a newly-created server binds to all available interfaces. Optional. Valid values: YES or ON binds (Default) NO or OFF does not bind You use this parameter whenever you run the BMC II C APIs as a service. When running a as service, you bind to a specific port number where you receive all network traffic. If you have multiple Ethernet cards, you can say you want to bind to the same port on all of the Ethernet cards (interfaces). Alternatively, you can bind to a specific interface by binding to an IP address. LocaleConfigFileName Note: For more information about binding and the ServerAllInterfaces cell configuration parameter, see the BMC Impact Solutions: General Administration guide. directory path for language support where the catalog files and the.load file are located. The default is under the./locale path: for example, installdirectory/iiws/locale/iiws.load. Appendix A BMC Impact Integration Web Services Server Administration 135

136 Editing the configuration file Editing the configuration file 1 If necessary, copy the iiws.conf file from the drive:\installdirectory\mcell or installdirectory/mcell directory to the corresponding location of your web service server installation. 2 Using a text editor, open the iiws.conf file. 3 Modify the values of the required parameters and any optional parameters that you want to include (described in Table 25 on page 124). NOTE You can use the following substitution parameters in the configuration (.conf) and trace (.trace) files: %H home directory %C configuration directory %L log file directory %T temporary file directory %P Integration name %N Instance name For more information about path value variables, see the BMC Impact Solutions: Administration guide. 4 Optional. Modify the file to include any optional BMC II Web Services server parameters that you want to use. Table 25 on page 124 lists these parameters. 5 Optional. Add any integration-specific configuration parameters (not directly related to BMC II Web Services) that you want to store with the BMC Impact Manager configuration data. 6 Save the file using the file name of your choice and the file extension.conf. 7 Ensure that the configuration file can be read by the user under whose permissions the web services server is running. 8 If you overrode the default location or name of the UniqueID.dat file, described in Table 25 on page 124, you must grant the web services server write access on the file. 9 If the BMC II Web Services server is running, restart it to initialize the changes. See Starting and stopping the BMC II Web Services Server on page BMC Impact Integration Developer s Kit Web Services Server Developer Guide

137 Trace file Trace file A sample iiws.trace file is located under drive:\installdirectory\mcell or installdirectory/mcell. By default, the trace functionality is enabled in the installdirectory/conf/servercfg.xml or drive:\installdirectory\conf \servercfg.xml file, as shown in the following example: svci:enabletrace="1" The BMC II Web Services server writes its logging messages to the iiws.trace file. Configure trace functionality as you would in a BMC Impact Manager product instance. To set up tracing, you must modify: the trace parameters in the iiws.conf file. For more information, see Editing the configuration file on page 136. the trace configuration file. See Editing the trace configuration file on page 138. For more information about the configuration files (*.conf and *.trace), see the BMC Impact Solutions: Administration guide. Figure 19 on page 138 depicts a sample trace file. Appendix A BMC Impact Integration Web Services Server Administration 137

138 Editing the trace configuration file Figure 19 Sample trace configuration file # BMC Impact Manager 3.2 # Cell trace configuration file # # Configuration: # This configuration mentions the destination for trace messages # on a module/level basis. It can also indicate destinations for # special tracing switches. # Each configuration line overrides any possible previous settings. # # Format of a configuration line: # Module Level Destination # Module SWITCH Switch Destination # Where # Module = name of module (see list 'Module' below) # Level = message level (see list 'Level' below) # Switch = switch name (see list 'Module Switch' below) # Destination = destination file name or predefined value # (see list 'Destination' below) # A wildcard can be specified for Module and for Level : # ALL or * ALL ALL stderr ALL VERBOSE no Editing the trace configuration file 1 If necessary, copy the iiws.trace file from the drive:\installdirectory\mcell or installdirectory/mcell directory to the working directory of your BMC II Web Services Server installation. 2 In a text editor, open the iiws.trace. 3 Modify the file according to the instructions in the BMC Impact Solutions: Administration guide. NOTE You can use the following substitution parameters in the.trace file.: %H home directory %C configuration directory %L Integration log file directory %T Integration temporary file directory %P Integration name %N Instance name For more information about path value variables, see the BMC Impact Solutions: Administration guide. 138 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

139 mcell.dir file 4 Save the file using the integrationname.trace naming convention. 5 Grant the integration account read access to the integrationname.trace file. 6 Ensure that the TraceConfigFileName parameter in the iiws.conf file points to the location in which you saved the integrationname.trace file. 7 Save the file using the file name of your choice and the file extension.trace. 8 Ensure that the trace file can be read by the user under whose permissions the BMC II Web Services Server is running. 9 Important. Ensure that the TraceConfigFileName parameter in the.conf file points to the location in which you saved the.trace file. 10 If the server is running, you must stop and restart it to make sure the configuration changes go into effect. For procedures for starting and stopping the sever, see Starting and stopping the BMC II Web Services Server on page 59. mcell.dir file The mcell.dir file lists the identifying information for all BMC Impact Manager product instances (cells) and event receivers (WSCELL) to which your implementation can connect and communicate. It is used to look up a BMC Impact Manager product instance or web services server name and to determine its host, port, and encryption key. TIP In the configuration file, ensure that the ServerDirectoryName parameter points to the directory location of the mcell.dir file on the BMC II Web Services Server. Editing the Integration mcell.dir file See How to synchronize BMC II Web Services Server and BMC IM cell connections on page 38 for the procedure for editing the respective mcell.dir files of the BMC Impact Manager instance and of the BMC II Web Services Server installation. Appendix A BMC Impact Integration Web Services Server Administration 139

140 Editing the Integration mcell.dir file 140 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

141 Appendix B Error Messages and Codes B This appendix describes the BMC II Web Services error messages. It also describes the underlying BMC II C API error codes and BMC Impact Manager core communications error codes to which the Web Services messages refer. 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 BMC II Web Services Server error messages BMC II Web Services generate the following text messages and return them to the web services client. Several of these text messages contain BMC II C API error codes (indicated in the text by the variable BMCII Error Code). When you see such an error code in the text, you can refer to corresponding error code in Table 26 on page 144. Then you can refer to a description of the BMC II C API error and a possible response under the heading Error descriptions on page 146. NOTE User responses and troubleshooting information for the BMC II Web Services error messages is provided through the BMC Software s Developer Connection Web site at Error <BMCII Error Code> connecting to cell, <Cell Name> Explanation: A connection problem exists in the BMC II C API and is reflected in the bmciiws_connect call. Appendix B Error Messages and Codes 141

142 BMC II Web Services Server error messages Error closing connection Explanation: A disconnection problem exists in the BMC II C API and is reflected in the bmciiws_disconnect call. Error: No name-value information in the event Error creating message Error creating message class and type Error <BMCII Error Code> setting slot Explanation: The web services server has received an empty event from the C API function in the bmciiws_send call. Explanation: The BMC II C API function generated an error in creating a message to be sent to a cell in the bmciiws_send call. Explanation: The BMC II C API function generated an error in setting the message type to be sent to the cell in the bmciiws_send call. Explanation: The BMC II C API function generated an error in setting the slot name and value in the bmciiws_send call. Error <BMCII Error Code> setting slot list <Index in the List> Failed to send message to cell Error getting selector names Explanation: The BMC II C API function generated an error in setting the slot (list type) name-value in the bmciiws_send call. Explanation: The BMC II C API failed to send the message to the cell in the bmciiws_send call. Explanation: The BMC II C API failed to get selector names in the bmciiws_getfilternames call. The client context is not subscribed to the requested filter Explanation: An invalid client context ID has been entered in the polling call bmciiws_getevents to get events. Error <BMCII Error Code> initiating query Explanation: The BMC II C API generated an error when issuing the bmciiws_query call to a cell. 142 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

143 BMC II Web Services Server error messages Error <BMCII Error Code> issuing query Invalid time error Invalid result handle Error cleaning up cell handles Invalid result handle Error retrieving result count for query Invalid start index Invalid result handle Result count not found Invalid start index Explanation: The BMC II C API generated an error when issuing the bmciiws_query call to a cell. Explanation: An incorrect date is entered in the query call bmciiws_querybydate. Explanation: The client has returned an invalid result handle to close the bmciiws_endquery call. Explanation: The BMC II C API generated an error in the bmciiws_endquery call when cleaning up the query handle ID in the web services server. Explanation: The client has provided an invalid result handle in the bmciiws_getqueryresultcount call. Explanation: The BMC II C API generated an error when retrieving the result count of the query call bmciiws_getqueryresultcount. Explanation: The client has supplied an invalid start index in the bmciiws_getqueryresult call. Explanation: The client has supplied an invalid result handle in the bmciiws_getqueryresult call. Explanation: The result count is unknown for fetching the query result in the bmciiws_getqueryresults call. Explanation: The client has requested a start index that is invalid or greater than the query result count in the bmciiws_getqueryresults call. Appendix B Error Messages and Codes 143

144 BMC II C APIs and core communications errors Failed to retrieve query result Explanation: The BMC II C API has failed to fetch a query result in the bmciiws_getqueryresult call. BMC II C APIs and core communications errors Errors with the BMCII prefix relate to all aspects of the BMC II C APIs, which are used to implement integrations with BMC Impact Manager instances. Core communication errors deal with the communications protocol between BMC Impact Manager cells. Core communication errors have the IM prefix and are described in Core communications errors on page 157. Some BMCII errors serve the same purpose as certain IM errors. However, the integration generates only one error for an error-producing event. Which error is generated depends on internal BMC II C APIs processes and cannot be determined before the generation of the error. Errors are listed numerically by error code and alphabetically by name. The alphabetic listing includes a description of each error. Errors listed By error code Table 26 on page 144 lists BMC II C APIs errors, arranged by error code. Table 26 BMC II C APIs Impact Integration Error Codes (part 1 of 3) Error Code Error Name Described on 0 BMCII_SUCCESS page BMCII_BAD_MESSAGE page BMCII_BAD_MALLOC page BMCII_BAD_SLOT_NAME page BMCII_BAD_SLOT_VALUE page BMCII_MEMORY_CORRUPTED_START page BMCII_MEMORY_CORRUPTED_END page BMCII_NOT_FOUND page BMCII_BAD_HEAD page BMCII_BAD_CLASS_NAME page BMCII_INDEX_OUT_OF_RANGE page BMCII_ERROR_WRONG_SLOT_TYPE page BMCII_BAD_PARAMETER page BMC Impact Integration Developer s Kit Web Services Server Developer Guide

145 Errors listed By error code Table 26 BMC II C APIs Impact Integration Error Codes (part 2 of 3) Error Code Error Name Described on -116 BMCII_NEED_MORE_MEMORY page BMCII_END_DELIMITER page BMCII_ERR_MISSING_CONFIG page BMCII_ERR_BAD_FILE_OPEN page BMCII_BAD_CONFIG page BMCII_BAD_EVENT_CREATE page BMCII_BAD_HOST_PORT page BMCII_INVALID_SERVER_NAME page BMCII_ERR_LOST_CONNECT page BMCII_ERR_BAD_OBJECT_CREATE page BMCII_COMM_LOCK_NOT_INIT page BMCII_BAD_MESSAGE_TYPE page BMCII_BAD_SOCKETS_INIT page BMCII_ERR_BAD_FILE_NAME page BMCII_BAD_SELECTOR_HEADER page BMCII_BAD_SELECTOR_NAME page BMCII_NO_MORE page BMCII_BAD_SELECTOR_FILE_FORMAT page BMCII_UNKNOWN_FUNCTION page BMCII_BAD_MAP_FILE_FORMAT page BMCII_BAD_MAP_LINE page BMCII_BAD_SELECTOR_LINE page BMCII_BAD_MAP_HEADER page BMCII_BAD_MAP_NAME page BMCII_MESSAGE_CORRUPTED page BMCII_INVALID_FUNCTION_FORMAT page BMCII_UNKNOWN_SLOT_TYPE page BMCII_ALREADY_INITED page BMCII_FAILED_START_RECV page BMCII_ALREADY_RUNNING page BMCII_TIMED_OUT page BMCII_BAD_RECV_EVENT page BMCII_BAD_MUTEX page BMCII_MAPSET_DISABLED page BMCII_MAP_LOOP_DETECTED page BMCII_SELECTOR_LOOP_DETECTED page BMCII_INCOMPATIBLE_VERSION page BMCII_EMPTY_SLOT_NAME page 150 Appendix B Error Messages and Codes 145

146 Error descriptions Table 26 BMC II C APIs Impact Integration Error Codes (part 3 of 3) Error Code Error Name Described on -177 BMCII_MUST_CALL_INIT page BMCII_NEED_LOCKS_FOR_THREAD page BMCII_UNKNOWN_TYPE page BMCII_MAP_DISABLED page BMCII_INVALID_CALL page BMCII_BAD_BAROC page BMCII_QUERY_REGISTRATION_FAILED page BMCII_NO_RESULT_YET page BMCII_BAD_PARSE page BMCII_REQUEST_OUT_OF_RANGE page BMCII_QUERY_ERROR page BMCII_QUERY_CONNECTION_DOWN page BMCII_ILLEGAL_QUERY page BMCII_EMPTY_MESSAGE page BMCII_FREED_NULL_POINTER page BMCII_CORRUPT_LIST page BMCII_TERM_CALLED page BMCII_MISSING_MOD_INFO page 154 Error descriptions BMCII_ALREADY_INITED BMCII_ALREADY_RUNNING Each BMC II C APIs error is listed alphabetically, along with its description and any prescriptive information. Explanation: The bmcii_init3() function has been called after the BMC II C APIs have already been initialized. User response: None. Calling bmcii_init3() more than once will not harm the integration (nor will it do anything positive, either). Explanation: The bmcii_startrecv function has been called after the Receive thread is already running. User response: None. Calling bmcii_startrecv more than once will not affect Receive thread operation. 146 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

147 Error descriptions BMCII_BAD_BAROC BMCII_BAD_CLASS_NAME BMCII_BAD_CONFIG BMCII_BAD_EVENT_CREATE BMCII_BAD_HEAD BMCII_BAD_HOST_PORT BMCII_BAD_MALLOC Explanation: The BAROC string that was passed to the BMC II C APIs using the bmcii_messagesetbaroc function is malformed and cannot be processed. User response: Correct the BAROC string syntax. Explanation: The class name is missing from an event or data message. The message information may be intended for a new message or as an attempt to overwrite an existing message. User response: Set the message class name using either the bmcii_setmessagetype or the bmcii_setmetaslotvalue function. Using the bmcii_setmetaslotvalue function is recommended. Explanation: The parameter specified in a configuration function call (bmcii_get_bool, bmcii_get_dir, bmcii_get_file, bmcii_get_num, or bmcii_get_string) is missing from the integration_name.conf file, or the parameter name was specified incorrectly in the function call. User response: Update the integration_name.conf file with the correct parameter name or fix the integration code where the configuration function is specified. Explanation: The BMC II C APIs are unable to create an event message. User response: See the trace log for information. Explanation: The header of a BAROC string that was passed to the BMC II C APIs Impact Integration using the bmcii_messagesetbaroc function is malformed or missing. The string cannot be converted into a message. User response: Correct the BAROC string syntax. Explanation: The host and/or port specified in one of the following functions is invalid or malformed: bmcii_connect, bmcii_setupserver, or bmcii_initqueryconnect. User response: Check the trace log to ensure that the host name and port number are formatted correctly in the function call code. Explanation: No memory is available to the BMC II C APIs. User response: Free existing system memory or add memory. Appendix B Error Messages and Codes 147

148 Error descriptions BMCII_BAD_MAP_FILE_FORMAT BMCII_BAD_MAP_HEADER BMCII_BAD_MAP_LINE BMCII_BAD_MAP_NAME BMCII_BAD_MESSAGE_TYPE BMCII_BAD_MESSAGE BMCII_BAD_MUTEX Explanation: There is an error in the specified map file. User response: View the trace log for additional information. Correct the map file, if necessary. Rerun the function that called the map file. Explanation: The header of one or more maps in the specified map file is missing or malformed. User response: Correct the header in the map file and rerun the function that called the map file. Explanation: There is a syntax error in a line in the specified map file. User response: View the trace log. It will specify the line that includes the error. Correct the map file. Rerun the function that called the map file. Explanation: The name of a map in the specified map file is missing or malformed. User response: Correct the map name in the map file. Rerun the function that called the map file. Explanation: The message type specified in the message is not included in the message type enumeration. User response: Ensure that the integration is using the correct version of the BMC II C APIs library. The specified message type may be supported by a version of the APIs that is not loaded. Explanation: The message is corrupted or includes a null parameter. User response: Check the integration code for invalid (null) values or a buffer overflow. Explanation: A mutex internal to the BMC II C APIs is invalid. User response: Check for a buffer overflow. Report the problem to BMC Developer Connection. 148 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

149 Error descriptions BMCII_BAD_PARAMETER BMCII_BAD_PARSE BMCII_BAD_RECV_EVENT Explanation: The integration called a function that included an invalid parameter. User response: Check the integration code. Explanation: The BMC II C APIs are unable to parse the response from the BMC Impact Manager product instance. User response: View the trace log for additional information. Report the problem to BMC Developer Connection. Explanation: An internal event is invalid. User response: Check for a buffer overflow. Report the problem to BMC Developer Connection. BMCII_BAD_SELECTOR_FILE_FORMAT BMCII_BAD_SELECTOR_HEADER BMCII_BAD_SELECTOR_LINE BMCII_BAD_SELECTOR_NAME Explanation: The specified selector set file contains an error. User response: View the trace log for additional information. Correct the selector set file. Rerun the function that called the selector set file. Explanation: The header of one or more selectors in the specified selector set file is missing or malformed. User response: Correct the header in the selector set file and rerun the function that called the selector set file. Explanation: There is a syntax error in a line in the specified selector set file. User response: View the trace log. It will specify the line that includes the error. Correct the selector set file. Rerun the function that called the selector set file. Explanation: The name of a selector in the specified selector set file is missing or malformed. User response: Correct the selector name in the selector set file. Rerun the function that called the selector set file. Appendix B Error Messages and Codes 149

150 Error descriptions BMCII_BAD_SLOT_NAME BMCII_BAD_SLOT_VALUE BMCII_BAD_SOCKETS_INIT BMCII_COMM_LOCK_NOT_INIT BMCII_CORRUPT_LIST BMCII_EMPTY_MESSAGE BMCII_EMPTY_SLOT_NAME BMCII_END_DELIMITER Explanation: The integration called a function that included a malformed or null slot name. User response: Check and modify the integration code. Explanation: The message contains a slot with a null value or an empty string. User response: Check and modify the integration code. Explanation: Microsoft Windows only. Sockets are not initialized because the BMC II C APIs determine the socket library version. The version of Windows on the integration host is not supported. User response: Verify that your integration is running only on OSes that are supported by the loaded version of the BMC II C APIs. For a list of supported OSes, see BMC Impact Integration Developer s Kit C API Developer Guide. Explanation: Internal error. User response: Ensure that the bmcii_init3() function was called correctly. Explanation: An internal list is corrupt. User response: Check the log for additional information. Report the problem to BMC Developer Connection. Explanation: Internal error. The result buffer is corrupt. User response: Check the log for more information. Remove the current receive buffer file described in the log file. A new file will be created. Explanation: A slot name in the message is set with an empty string. User response: Check and modify the integration code. Explanation: A BAROC string that the integration is formatting as a message is missing an END statement. User response: Verify the string format. Modify it, if necessary. 150 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

151 Error descriptions BMCII_ERR_BAD_FILE_NAME BMCII_ERR_BAD_FILE_OPEN BMCII_ERR_BAD_OBJECT_CREATE BMCII_ERR_LOST_CONNECT BMCII_ERR_MISSING_CONFIG BMCII_ERROR_WRONG_SLOT_TYPE BMCII_FAILED_START_RECV Explanation: The bmcii_loadselectorset function specifies a null pointer or empty string for the selector set file name. This error message can also apply to map set files specified with the bmcii_loadmapset function. User response: Check and modify the integration code. Explanation: The specified map set file (or selector set file) does not exist, or the integration does not have permission to access the specified file. User response: Verify that the correct file name is specified in the integration code. Verify that the file exists in the location specified in the function call and that the file name is spelled correctly. Update the integration s permissions for map and selector set files. Explanation: Internal error. The BMC II C APIs are unable to create a required object. User response: Check for a buffer overflow and appropriate the required memory resources. Report the problem to BMC Developer Connection. Explanation: The connection to the BMC Impact Manager product instance was broken while the integration was sending a message. User response: Disconnect from the BMC Impact Manager product instance. Then, reestablish the connection and resend the message. Explanation: The name and location of the mcell.dir file are not specified in the integration_name.conf configuration file. User response: Check the integration_name.conf configuration file. Make any necessary corrections. Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Explanation: The bmcii_startrecvthread function failed to create a new Receive thread. Appendix B Error Messages and Codes 151

152 Error descriptions BMCII_FREED_NULL_POINTER BMCII_ILLEGAL_QUERY BMCII_INCOMPATIBLE_VERSION BMCII_INDEX_OUT_OF_RANGE BMCII_INVALID_CALL BMCII_INVALID_FUNCTION_FORMAT User response: Check the logs and verify that the integration host computer supports POSIX or Windows native threads. Report the problem to BMC Developer Connection. Explanation: An internal list is corrupt. User response: Check the log for additional information. Report the problem to BMC Developer Connection. Explanation: The query is not supported by the loaded version of the BMC II C APIs. User response: For valid query types, see the BMC II C APIs product documentation. Explanation: The version of the structure passed by the bmcii_getfirstdirectoryinfo or bmcii_getnextdirectoryinfo function is not supported by the BMC II C APIs library in use. User response: Verify that the Version field is set properly before calling either function. Alternately, ensure that the most current library version is being used by the BMC II C APIs. Explanation: No more results are available in response to a request for the items in a list of values. User response: This is not an error. Stop requesting additional values. Explanation: Functions that must be called in a specific order were called out of order. User response: Check the log and the integration code. Recall the functions in the correct order. For more information, refer to the function descriptions in the BMC Impact Integration Developer s Kit C API Developer Guide or in the C API Reference Guide. Explanation: The map set (or selector set) specifies a function that includes one or more invalid parameters. User response: Modify the map set file or selector set file to correct the problem. 152 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

153 Error descriptions BMCII_INVALID_SERVER_NAME BMCII_MAP_DISABLED BMCII_MAP_LOOP_DETECTED BMCII_MAPSET_DISABLED BMCII_MEMORY_CORRUPTED_END BMCII_MEMORY_CORRUPTED_START BMCII_MESSAGE_CORRUPTED Explanation: The cell name specified in the bmcii_connect, bmcii_serversetup, or bmcii_queryinitconnect function is invalid. User response: Check cell name specified in the function and in the mcell.dir file. Explanation: The map specified in the bmcii_translate function call is disabled. User response: This is not an error. However, if the map was disabled unintentionally, enable it and rerun the bmcii_translate function. Explanation: The $domap function is creating a loop in the map set. User response: Correct the map set file to eliminate the loop. Explanation: The integration did not perform any translation operation because the specified map set was disabled. This error message does not necessarily describe an error, since disabling an entire map set is supported. User response: If disabling the map set is intentional, no response is necessary. If the map set was disabled unintentionally, enable the map set and rerun the bmcii_translate function. Explanation: An internal structure is corrupt. User response: Check for a buffer overflow and appropriate the required memory resources. Report the problem to BMC Developer Connection. Explanation: An internal structure is corrupt. User response: Check for a buffer overflow and appropriate the required memory resources. Report the problem to BMC Developer Connection. Explanation: The message that was passed to the BMC II C APIs is invalid or corrupt. User response: Verify that the correct message was passed. Check for a buffer overflow. Report the problem to BMC Developer Connection. Appendix B Error Messages and Codes 153

154 Error descriptions BMCII_MISSING_MOD_INFO BMCII_MUST_CALL_INIT BMCII_NEED_LOCKS_FOR_THREAD BMCII_NEED_MORE_MEMORY BMCII_NO_MORE BMCII_NO_RESULT_YET BMCII_NOT_FOUND Explanation: The event modification that was sent did not include an mc_ueid ID or event handle to identify the event that was to be modified. The data modification that was sent did not include an mc_udid ID or data handle to identify the data object that was to be modified. User response: Check the integration code to ensure that the required ID slots are included. Modify the message, if necessary. Explanation: The BMC II C APIs are not initialized. All Function calls (except for bmcii_getversion) can be performed only after bmcii_init3() is called. User response: Call the bmcii_init3() function and recall the failed function. Explanation: The bmcii_start RecvThread function cannot create a thread because the UseLocks parameter is missing from the configuration file or is included but set to NO or OFF. User response: Add the UseLocks parameter to the integration_name.conf configuration file and set it to ON. If UseLocks is already included in the file, change its value to ON. Explanation: Fatal error. Failure to allocate memory. User response: Free existing system memory or add memory. Explanation: There are no more items in the list. User response: This is not an error. Stop calling the iterating function. Explanation: A query result has not yet been returned. User response: This is not an error. Recall bmcii_getqueryreply until the BMC Impact Manager product instance returns a reply. Explanation: The requested item (such as a slot) does not exist. User response: Check the integration code to verify that the requested item exists and is spelled correctly in the code. 154 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

155 Error descriptions BMCII_QUERY_CONNECTION_DOWN BMCII_QUERY_ERROR Explanation: The query connection was broken during the processing of a query. User response: Reestablish the query connection and recall the failed query. Explanation: The BMC Impact Manager product instance returned an error. User response: For more information, see the BMC Impact Manager product instance and integration logs. BMCII_QUERY_REGISTRATION_FAILED BMCII_REQUEST_OUT_OF_RANGE BMCII_SELECTOR_LOOP_DETECTED BMCII_SUCCESS BMCII_TERM_CALLED BMCII_TIMED_OUT Explanation: Following an attempt to establish a query connection with a BMC Impact Manager product instance using the bmcii_initqueryconnect function, the BMC Impact Manager product instance returned an error and the connection failed. User response: Check the log for more information. Explanation: The requested placeholder is not in the list. User response: This is not an error. Stop calling the iterating function. Explanation: The $doselector function is creating a loop in the selector set. User response: Correct the selector set file to eliminate the loop. Explanation: The function call (specified by its return code) was successful. This is not an error. This code is returned for all successful function calls. User response: None. Explanation: The integration called a function after the BMC II C APIs were terminated. User response: Re-initialize the BMC II C APIs and recall the required function. Examine the integration code and correct any problems. Explanation: The timeout period specified in the function expired before any results were returned. Appendix B Error Messages and Codes 155

156 Error descriptions BMCII_UNKNOWN_FUNCTION BMCII_UNKNOWN_SLOT_TYPE BMCII_UNKNOWN_TYPE User response: This is not an error. You can recall the function until the results are available. Explanation: The loaded map set or selector set file specifies a BMC II C APIs function not supplied by the BMC II C APIs library in use. User response: Check the map set or selector set file to ensure that the appropriate function is specified. Verify which version of the BMC II C APIs library is loaded to ensure compatibility. Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Explanation: The message type that is being passed to the message is unknown. This can happen when setting the message type with the bmcii_setmessagetype function or setting META_MSG_TYPE using the bmcii_setmetaslot function. User response: In the integration code, check the parameter value being passed as the message type. 156 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

157 Core communications errors Core communications errors Errors with the IM prefix are core communications errors in the BMC II C APIs. Errors that are related to other aspects of the BMC II C APIs are described in BMC II C APIs and core communications errors on page 144. Errors are listed by error code and alphabetically (starting on page 158). The alphabetic listing includes a description of each error. Errors listed by error code Table 27 lists BMC II C APIs core communications errors, arranged by error code. Table 27 Core Communications Error Codes (part 1 of 2) Error Code Error Name Described on 0 IM_ERR_NONE page IM_ERR_UNINITIALIZED page IM_ERR_INIT_CONFIG page IM_ERR_TRACE_CONFIG page IM_ERR_INIT_COMM_OUT page IM_ERR_INIT_COMM_IN page IM_ERR_INIT_MSGS page IM_ERR_INIT_PORT_RANGE page IM_ERR_INIT_CRYPT page IM_ERR_NOTRANSPORT page IM_ERR_NOENDPOINT page IM_ERR_NOBIND page IM_ERR_MEMFAULT page IM_ERR_BAD_IP page IM_ERR_BAD_LOCATION page IM_ERR_NAME_LOOKUP page IM_ERR_SVC_UP page IM_ERR_SVC_DOWN page IM_ERR_INVALID_CNC page IM_ERR_INVALID_MSGTYPE page IM_ERR_CONNECT page IM_ERR_TIME_OUT page IM_ERR_NOCONNECT page IM_ERR_NOBUFFER page 160 Appendix B Error Messages and Codes 157

158 Error descriptions Table 27 Core Communications Error Codes (part 2 of 2) Error Code Error Name Described on 24 IM_ERR_NOCONTACT page IM_ERR_SEND page IM_ERR_MAX page 160 Error descriptions IM_ERR_BAD_IP IM_ERR_BAD_LOCATION IM_ERR_CONNECT IM_ERR_INIT_COMM_IN IM_ERR_INIT_COMM_OUT Each core communications error is listed alphabetically and includes a description of the error and prescriptive information, if any is available. Explanation: The IP address that was passed to the bmcii_connect, bmcii_initqueryconnect, or bmcii_setupserver function is invalid. User response: Verify the correct IP address of the target BMC Impact Manager product instance, and ensure that the correct address is specified in your integration code. Explanation: The host name that was passed to the bmcii_connect, bmcii_initqueryconnect, or bmcii_setupserver function is invalid. User response: Verify the host name of the target BMC Impact Manager product instance, and ensure that the correct name is specified in your integration code. Explanation: The integration s attempt to connect to a BMC Impact Manager product instance (using bmcii_connect or bmcii_initqueryconnect) failed. The integration will not retry to reconnect. User response: Check that the destination is defined correctly in the mcell.dir file and that the requested server is on destination computer. Explanation: Initialization of the inbound communication module in the BMC II C APIs failed. User response: Stop and restart the integration. Explanation: Initialization of the outbound communication module in the BMC II C APIs failed. 158 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

159 Error descriptions IM_ERR_INIT_CONFIG IM_ERR_INIT_CRYPT IM_ERR_INIT_MSGS IM_ERR_INIT_PORT_RANGE IM_ERR_INVALID_CNC IM_ERR_INVALID_MSGTYPE User response: Stop and restart the integration. Ensure that no other application is using the requested port. Explanation: The integration home directory, the path to the.conf configuration file or the contents of the configuration file is invalid. User response: Verify that all integration code references to the integration home directory and to the.conf file are correct. Verify that the.conf file does not contain any errors. Explanation: The connection was made using an invalid encryption key. User response: For information about using encryption, see the BMC Impact Integration Developer s Kit Impact Integration C APIs Developer Guide. Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Explanation: The port range specified with the ConnectionPortRange parameter in the.conf file is invalid. User response: Specify a port range that is valid for the host operating system. For more information about the ConnectionPortRange parameter, see the BMC Impact Integration Developer s Kit Impact Integration C APIs Developer Guide. Explanation: The integration passed or received an invalid or closed connection handle. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode). User response: Discard the connection handle that is currently in use: If the integration initiated the connection with the problematic handle, make a new connection attempt. A new handle is assigned. If the integration was acting as a server, continue listening for another connection request. Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Appendix B Error Messages and Codes 159

160 Error descriptions IM_ERR_MAX IM_ERR_MEMFAULT IM_ERR_NAME_LOOKUP IM_ERR_NOBIND IM_ERR_NOBUFFER IM_ERR_NOCONNECT IM_ERR_NOCONTACT Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Explanation: The BMC II C APIs cannot allocate memory. User response: Do one or both of the following: free resources or stop and restart the integration. Also, check the integration code for memory leaks. Explanation: Host name lookup failed. User response: Check the entries in the mcell.dir file and/or check that the DNS service is working correctly. Explanation: The integration cannot start server mode using the specified port number. The port is being used by another application or is privileged. User response: Check whether the port is in use. If the port is in use, specify that the integration use a different port or stop the application that is currently using the port. If port use is privileged, specify that the integration use a different port or run the integration as privileged user. Explanation: The message buffer is full. User response: Increase the buffer size. Modify the value of the MessageBufferSize parameter in the.conf configuration file. Explanation: The integration sent a message containing the META_FAIL_IF_UNCONNECTED metaslot when no connection was established. User response: None. Explanation: Currently, no connection is established to the message destination. The message will be buffered. User response: Ensure the availability of the BMC Impact Manager product instance or integration to which the message is directed. 160 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

161 Error descriptions IM_ERR_NOENDPOINT IM_ERR_NONE IM_ERR_NOTRANSPORT IM_ERR_SEND IM_ERR_SVC_DOWN IM_ERR_SVC_UP IM_ERR_TIME_OUT Explanation: Internal error. User response: Report the problem to BMC Developer Connection. Explanation: No error. User response: None. Explanation: The TCP/IP stack on the integration host is not available. User response: Verify that the operating system recognizes the TCP/IP stack and that the appropriate adapters are available. Explanation: The connection attempt failed. This error is displayed for connections initiated by the integration (acting in client mode) and connections directed to the integration (acting in server mode). User response: If the integration initiated the connection failed attempt, you can make an additional connection attempt. If the integration was acting as a server, continue listening for additional connection requests. Explanation: The integration called the bmcii_stopserver function when server mode was not running. User response: Check the integration code to determine why bmcii_stopserver was called two (or more) times. Explanation: The integration called the bmcii_startserver when the integration was already in server mode. User response: Check the integration code to determine why bmcii_startserver was called two (or more) times. Explanation: The timeout period expired for one of the functions that uses a timeout. This is a notice, not an error. User response: None, unless you want to rerun the function that timed out. Appendix B Error Messages and Codes 161

162 Error descriptions IM_ERR_TRACE_CONFIG IM_ERR_UNINITIALIZED Explanation: The tracing configuration file (integration_name.trace) is missing, configured incorrectly, or described incorrectly in the integration code. User response: Locate the file. Ensure that integration code includes the correct name and path to the file. Fix any errors that the file may contain. Explanation: Internal error. User response: Report the problem to BMC Developer Connection. 162 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

163 Appendix C Sample Client Files C This appendix describes the sample client files that are packaged with the BMC II Web Services Server installation. It describes the following topics List of sample client files Event Listener Web Services Description Language (WSDL) file Event listener server Event dispatcher Namespaces Data types Messages Operations Bindings Service Listenercfg.xml file Adding SSL parameters to the listenercfg.xml file List of sample client files The BMC II Web Services Server installation includes sample files that you can find under the $installdirectory/samples or %installdirectory%\samples subdirectory. The following samples address Systinet C++ query implementations and can be found under the /waspc/test_query or \waspc\test_query subdirectory: Table 28 Sample client files: Systinet C++ queries (part 1 of 2) File name string_util.cpp string_util.h test_func.cpp test_imsw_api.txt Description contains functions that work with string structures the accompanying header file for the sample code containing functions that work with string structures reads the test functions in the input file example of input file in which test functions are specified Appendix C Sample Client Files 163

164 List of sample client files Table 28 Sample client files: Systinet C++ queries (part 2 of 2) File name test_imws_api.cpp test_imws_api.h test_util.cpp Description contains calls for specified BMC II Web Services functions such as tracing, client startup, cell connection, and so forth the accompanying header file for these BMC II Web Services calls a script for testing specified BMC II Web Services functions Under the /waspc/test_events or \waspc\test_events subdirectory, you can find Systinet C++ client code for building a listener client. Table 29 File name EventListener.wsdl listenercfg.xml client.cpp Sample client files: Systinet C++ listener client Description exposes the dispatch operations that are required to build a listener client listener client configuration file demonstrates how to subscribe to events through the EventListener.wsdl interface You can find a sample.net C# implementation under the.net subdirectory. View the readme.txt file under the /.NET/TestIIWs or \.NET\TestIWs subdirectory to see which operations are implemented and how to launch the sample. You can refer to.net C# toolkit sample on page 76 for more information. You can find a sample Axis Java implementation under the Axis subdirectory. Table 30 File name dataqueries receiveevents sendevents wsdl Sample client files: Axis Java implementations Description provides a programming demo that shows how to write a client which queries events, data, and service model components in the BMC IM cell shows how to write a client that subscribes to and retrieve events from a BMC IM cell indicates how to send events to the BMC IM cell through BMC IM Web Services Server contains the impactmanager.wsdl and supplemental schema definition files You can refer to Apache Axis toolkit sample on page 77 for more information. 164 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

165 Event Listener Web Services Description Language (WSDL) file Event Listener Web Services Description Language (WSDL) file The BMC II Web Services package also contains an EventListener.wsdl file that exposes event dispatch operations, which a developer can access to build a custom event listener. To invoke the dispatch operations in the EventListener.wsdl, you can use the toolkit of your choice, as long as it support event listener libraries. You can write your client in any programming language that is compatible with your toolkit. The EventListener.wsdl exposes two event dispatch operations that accept one or more events. Using the dispatch operations, you can create your own event listener libraries to implement callbacks in a publish-subscribe scenario. You can write the event listener in any programming language that is supported by your toolkit. NOTE In the current implementation of the BMC II Web Services server, the event dispatcher component only invokes the _dispatch operation. It does not invoke the _dispatchlist operation. Figure 20 on page 165 depicts how the dispatch operations are implemented in BMC II Web Services. Figure 20 Dispatch Operations in EventListener.wsdl Appendix C Sample Client Files 165

166 Event listener server Event listener server Using the event listener libraries of your toolkit, you configure on the client an event listener server with a specific callback URL and port number. The client registers the callbacks, which contain the event handler logic, with the event listener server. When the event listener server receives an event, it dispatches it to a callback in the list of callbacks that it maintains. The callback invokes the event handler logic. Event dispatcher The BMC II Web Services Server starts the WSCELL message receiver and begins to receive events propagating from connected BMC Impact Manager instances. The BMC II Web Services Server checks the subscription manager for subscriber clients. The Web server determines the type of subscriber (polling or callback) based on the format of the subscription request. If the request contains a callback URL, then the subscription is for a callback client. The server invokes an internal send() API call that the event dispatcher has exposed in behalf of the callback client. The event dispatcher determines the callback URL of the event listener server from the client context. It then invokes one of the dispatch operations to send one or more events to the event listener server. The client manages the events based on the event handler logic that you have implemented. Namespaces The EventListener.wsdl declares the following namespace URIs. Table 31 Namespaces: EventListener.wsdl Type/Prefix Namespace target default xsd event btypes soap wsdl BMC Impact Integration Developer s Kit Web Services Server Developer Guide

167 Data types Data types In the EventListener.wsdl, the data types enclose the schema definitions and the imported schema definition file Event.xsd. <wsdl:types> <xsd:schema> <xsd:import namespace= schemalocation= Event.xsd /> </xsd:schema> </wsdl:types> The Event.xsd file defines the data types Event and ArrayOf_Event in its schema definition. Messages The EventListener.wsdl contains two asynchronous one-way messages: Dispatch_Request and DispatchList_Request. The Dispatch_Request carries a single event; the DispatchList_Request carries one or more events (an array of events). Each request message has a corresponding HTTP-generated response that acknowledges the receipt of the request. Dispatch_Request The event dispatcher sends the Dispatch_Request message to the event listener to communicate a single event. <wsdl:message name= Dispatch_Request > <wsdl:part name= Event element= event:event_element /> </wsdl:message> Table 32 Message Parts: Dispatch_Request Name Element/Type Description Event event:event_element complex type that specifies the name of a single event element which the event dispatcher sends as a request to the listener server. The event type extends the complex type ArrayOf_NameValue. Appendix C Sample Client Files 167

168 Operations Dispatch_Response The Dispatch_Response message is an acknowledgement and does not carry any content. <wsdl:message name= Dispatch_Response /> DispatchList_Request The event dispatcher sends the DispatchList_Request message to the listener server to communicate one or more events (an array of events). <wsdl:message name= DispatchList_Request > <wsdl:part name= ArrayofEvent_element element= event:eventarray_element /> </wsdl:message> Table 33 Message Parts: DispatchList_Request Name Element/Type Description ArrayOfEvent_element event:eventarray_element complex type that specifies the name of one or more events that the event dispatcher sends to the listener server DispatchList_Response The DispatchList_Response is an acknowledgement and carries no content. <wsdl:message name= DispatchList_Response /> Operations dispatch The event dispatcher on the web services server invokes the dispatch operation to send an event to a specified event listener on a specified client. <wsdl:operation name= dispatch parameterorder= Event > wsdl:input message= tns:dispatch_request /> </wsdl:operation> 168 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

169 Operations Message Name Type Description tns:dispatch_request One way message sent by the event dispatcher to a specified listener server residing on a specified client. The message contains an event type to which the client has subscribed. The event dispatcher does not expect a response. Parameter Name Direction Element Name Description Event Out Event_element a complex type that extends the ArrayOf_NameValue type. It contains a single event. dispatchlist NOTE While the dispatchlist operation is exposed in the current implementation, the event dispatcher does not invoke the call. The event dispatcher invokes the dispatchlist operation to send one or more events to the specified event listener residing on the specified client. <wsdl:operation name= dispatchlist parameterorder= ArrayOfEvent_element > wsdl:input message= tns:dispatchlist_request /> </wsdl:operation> Message Name Type Description tns:dispatchlist_request One way message sent by the event dispatcher to a specified listener server residing on a specified client. The message contains one or more events to which the client has subscribed. The event dispatcher does not expect a response. Appendix C Sample Client Files 169

170 Bindings Parameter Name Direction Element Name Description ArrayOfEvent_element Out event:eventarray_ element complex type that specifies the name of one or more events that the event dispatcher sends to the listener server Bindings The Event Listener binding is available through the SOAP message format. The SOAP messages are transmitted over the wire through the HTTP transport protocol. The style of the SOAP messages conforms to the conventions of XML documents. The EventListener.wsdl uses the document style for its SOAP bindings. The following syntax describes how the Event Listener binding to the SOAP protocol is made available for transmission: <wsdl:binding name= EventListener type= tns:eventlistener > <soap: binding transport= http style= document /> The message requests and responses are represented in literal formats. (The message requests are one-way messages, and the responses are acknowledgements only.) When transmitted, the data are formatted based on the schema definitions referenced in the WSDL document. Encoding rules are not applied to the data. No fault messages are generated. The soap:operation elements are depicted on page 170. dispatch <wsdl:operation name= dispatch > <soap:operation soapaction= EventListener#dispatch#KExOYW11VmFsdWVQYW1yczspVg== style= document /> <wsdl:input> <soap:body use= literal /> </wsdl:input> <wsdl:output> <soap:body use= literal /> </wsdl:output> </wsdl:operation> 170 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

171 Service Message Part Use Schema Definition Input literal tns:dispatch_request Output literal none dispatch list <wsdl:operation name= dispatchlist > <soap:operation soapaction= EventListener#dispatchList#KFtMTmFtZvZhbHV1UGFpcnM7KVY== style= document /> <wsdl:input> <soap:body use= literal /> </wsdl:input> <wsdl:output> <soap:body use= literal /> </wsdl:output> </wsdl:operation> Message Part Use Schema Definition Input literal tns:dispatchlist_request Output literal none Service The service element of the EventListener.wsdl is declared in the following figure: <wsdl:service name= EventListener > <wsdl:port name= EventListener binding= tns:eventlistener > <soap:address location: urn:unknown-location-uri /> </wsdl:port> </wsdl:service> When configuring the event listener server, you can specify the value of its soap:address location element on the web service client. In the WASP Server for C++ toolkit implementation, the event listener server reads this value at runtime based on the values contained in the listenercfg.xml file, specifically the port number value. So if the listenercfg.xml file has its port attribute defined as 7070, then the EventListener.wsdl reveals the location as In other web services toolkit implementations, the toolkit s specific startup process for its event listener server substitutes a corresponding value for the soap:address location element. Appendix C Sample Client Files 171

172 Listenercfg.xml file WARNING Do not modify the EventListener.wsdl or any of the schema definition files found in the same directory. Other toolkits generate WSDL files. When building the service, specify the EventListener.wsdl, not other generated WSDL files. Your code will not compile properly if you do not follow these directives. Listenercfg.xml file The default declaration of the listenercfg.xml file is shown below in the following figures. Note that the default client port number is <waspc-config xmlns:wasp="urn:waspserver" xmlns:cppa= urn:cppadaptor xmlns:sep= urn:serviceendpoint xmlns:svci= urn:serviceinstancerepository xmlns:trans= urn:transportrepository > <wasp:import ref="conf/serverbase.xml"/> <trans:transport trans:class= WASP_HTTPTransportServer trans:scheme= server-http xmlns:hts= urn:httptransportserver hts:reusecount= 15 hts:reusetimeout= 30 hts:rwtimeout= 30 hts:accepttimeout= 5 hts:chunked= true hts:port= 7070 hts:hostname= $AUTO$ hts:dispatcher= DefaultDispatcher hts:singlethread= 0 hts:maxsparethreads= -1 hts:maxthreads= -1 /> <sep:serviceendpoint sep:dispatcherref= DefaultDispatcher sep:adaptorref= DefaultCppAdaptor cppa:wsdl= EventListener.wsdl sep:url= /EventListener > <cppa:instance cppa ref= EventListener /> </sep:serviceendpoint> <svci:serviceinstance svci:name EventListener svci:class= EventListenerServer /> <waspc-config> 172 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

173 Adding SSL parameters to the listenercfg.xml file Adding SSL parameters to the listenercfg.xml file In the %installdirectory%\samples or $installdirectory/samples subdirectory, you can find a listenercfg.security.xml file. It contains the required elements and attributes that you must incorporate within the listenercfg.xml file to enable security. You can copy the text of the listenercfg.security.xml file into the listenercfg.xml to enable an SSL secure client. The sample client matches trusted certificates with those contained in the certs subdirectory of the server, as indicated by the trusteddir element: <ssl:trusteddir>openssl/certs</ssl:trusteddir>. The following figure shows the listenercfg.xml file with SSL parameters, highlighted in bold, incorporated into it. NOTE The library file WASPOpenSSL.dll, referenced in this example, is for a Windows implementation. The library file libwasp_openssl.so is for Linux and Solaris implementations. <waspc-config xmlns:wasp="urn:waspserver" xmlns:cppa= urn:cppadaptor xmlns:sep= urn:serviceendpoint xmlns:svci= urn:serviceinstancerepository xmlns:trans= urn:transportrepository > <wasp:import ref="conf/serverbase.xml"/> <trans:transport trans:class= WASP_HTTPTransportServer trans:scheme= server-http xmlns:hts= urn:httptransportserver hts:reusecount= 15 hts:reusetimeout= 30 hts:rwtimeout= 30 hts:accepttimeout= 5 hts:chunked= true hts:port= 7070 hts:hostname= $AUTO$ hts:dispatcher= DefaultDispatcher hts:singlethread= 0 hts:maxsparethreads= -1 hts:maxthreads= -1 /> <wasp:externallibrary> <wasp:path>waspopenssl.dll</wasp:path> </wasp:externallibrary> <trans:transport xmlns:htc= urn:httptransportclient xmlns:htcssl= urn:httpsopenssltransportclient trans:class= WASP_HTTPSOpenSSLTransportClient trans:scheme= https htc:retrycount= 10 htc:retrytime= 100 htc:reusecount= 100 Appendix C Sample Client Files 173

174 Adding SSL parameters to the listenercfg.xml file htc:reusetimeout= 30 htc:rwtimeout= 30 htc:conntimeout= 30 htc:http10= false htc:chunked= false > <htcssl:context htcssl:class= WASP_OpenSSLContextFactoryImpl xmlns:ssl= urn:opensslcontextfactory ssl:verify= yes > <ssl:trusteddir>..openssl/certs</ssl:trusteddir> </htcssl:context> </trans:transport> <sep:serviceendpoint sep:dispatcherref= DefaultDispatcher sep:adaptorref= DefaultCppAdaptor cppa:wsdl= EventListener.wsdl sep:url= /EventListener > <cppa:instance cppa ref= EventListener /> </sep:serviceendpoint> <svci:serviceinstance svci:name EventListener svci:class= EventListenerServer /> <waspc-config> Restart the client after you save the file. 174 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

175 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Index Symbols $ClassName function 114 $doselector function, description 115 $Format function 116 $function_name function 114 $GmtTime function 116 $HostName function 114 $LD_LIBRARY_PATH 32 $LocalTime function 116 $MCELL_HOME 39 $PATH 32 $SHLIB_PATH 32 $slotmissing function 116 $slotpresent function 115 $TimeT function 116 %C substitution parameter 136, 138 %H substitution parameter 136, 138 %L substitution parameter 136, 138 %MCELL_HOME% 39 %N path value variable 136, 138 %P substitution parameter 136, 138 %PATH% 31 %s 116 %T substitution parameter 136, 138 A administration BMC Impact Integration Web Services Server 64, 106 editing iiws.conf file 136 editing iiws.selector 120 editing iiws.trace file 138 iiws.conf file 123 iiws.selector file 106 iiws.trace file 137 starting BMC Impact Integration Web Services Server 59 API (Application Program Interface) Basic C 16 audience presumed knowledge 105 roles 105 B BAROC (Basic Recorder of Objects in C) malformed string 147 missing END statement error 150 Basic C APIs initialization error 154 relation to Web services 16 BMC Developer Connection description 19 BMC Impact Integration Web Services asynchronous 82 client programming 74 security 66 BMC Impact Integration Web Services Server adminstration 106 BMC Impact Integration Developer s Kit 105 callbacks 16 components 15 guaranteed event delivery 89 imserv 60 installation package 22 mcell.dir 17 OpenSSL 23 queries 82 receiving events 88 required configuration tasks 38 selector processing 107 send request 82 servercfg.xml 57 SOAP messaging 17 starting 59 subscription requests 89 Systinet WASP server 16 updating parameters 57 WASP library files 16 BMC Impact Manager invalid name 153 returning query error 155 BMC Performance Manager 54 BMC Software, contacting 2 bmcii_connect function, invalid cell name 153 bmcii_getfirstdirectoryinfo function, error 152 bmcii_getnextdirectoryinfo function, error 152 bmcii_init function, error calling 150 Index 175

176 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z bmcii_initqueryconnect function, failure 155 bmcii_loadmapset function, file name error 151 bmcii_loadselectorset function, failure 108 bmcii_loadselectorset function, file name error 151 bmcii_queryinitconnect function, invalid cell name 153 bmcii_serversetup function, invalid cell name 153 bmcii_setmessagetype function, specifying unknown message type 156 bmcii_setmetaslot function, specifying unknown message type 156 bmcii_startserver function, error 161 bmcii_stopserver function, error 161 buffering bmciiws_connect 82 buffer, maximum size 126 corrupt buffer error 150 full buffer error 160 MessageBufferReconnectInterval parameter 127 MessageBufferSize parameter 126 messages 160 overflow 148, 149, 153 reconnect interval 127 C cache directory 30 callback URL 91, 97 callbacks description 95 cells invalid name error 153 ChangeDate parameter, message selector set header 111 class definition queries 83 classes missing class name 147 classes, specifying in translation maps 114 client code samples 30 client context ID 90 client proxy code generating 75 list of operations 78 programming language 75 sample source and header files 76 toolkit implementation 81 ClientSourceIP configuration parameter 125 ClientSourcePort configuration parameter 125 compilers 23 configuration.iiws.conf file 123.load file 49.mrl file 49 BMC Impact Integration Web Services Server 38 defining propagate rules 49 http-server.xml 56 MaxResponseEventListSize parameter 57 mcell.dir 38 security 66 servercfg.xml 57 updating server parameters 57 configuration file (.conf file) missing configuration information 151 configuration file (iiws.conf file) editing 123, 136 overview 123 substitution parameters 136 configuration files parameters 124 substitution parameters 138 TraceConfigFileName parameter 131 configuring configuration file parameters 124 iiws.conf 124 Trace parameter 131 TraceConfigFileName parameter 131 TraceDefaultFileName parameter 131 TraceFileAppend parameter 132 TraceFileHistory parameter 132 TraceFileSize parameter 132 TraceSrc parameter 131 connecting, maximum reconnect interval 127 connection handles, invalid 159 ConnectionPortRange configuration parameter 126 ConnectionPortRange parameter, error 159 ConnectionPortReuse configuration parameter 126 connections bmciiws_connect 82 broken connect error 151 broken query connection 155 destination availability error 160 error accepting 161 error requesting 161 failure due to META_FAIL_IF_UNCONNECTED metaslot 160 invalid handle 159 TCP/IP not available 161 ConnectionSetupTimeOut configuration parameter 125 custom event listener libraries dispatch operations 165 programming language 165 customer support 3 D data types, in EventListener.wsdl 167 Description parameter in message selector header 112 in message selector set header 111 dispatch bindings 170 operations 168, 169 Dispatch_Request, message 167 dispatchlist, operation BMC Impact Integration Developer s Kit Web Services Server Developer Guide

177 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z DispatchList_Request, message 168 dispatchlist_request, message 169 E embedding message selectors 108 Enable parameter in message selector header 112 in message selector set header 111 encryption Encryption parameter 126 Encryption configuration parameter 126 encryption, invalid key error 159 environment variables Microsoft Windows installation 31 UNIX installation 32 errors (C API) $doselector loop 155 bad function call order 152 bad message 148 bad message type 148 bad or missing map header 148 bad or missing selector header 149 bad slot name 150 bad slot value 150 Basic C API errors 144 broken connection 151 broken query connection 155 cannot find mcell.dir file 151 corrupt buffer 150 disabled map set 153 failed query connection attempt 155 functions called after termination 155 initializing the Basic C APIs 154 insufficient memory 147 invalid cell name 153 invalid function parameter 149 invalid internal event 149 invalid map set parameters 152 invalid mutex 148 invalid or corrupt message 153 invalid or incorrect host or port 147 invalid selector set parameters 152 lists of C API error codes 144 malformed BAROC string 147 map disabled 153 map set file name 151 map set file syntax 148 map set loop 153 memory allocation 154 message modification 154 missing BAROC END statement 150 missing class name 147 missing event or data handle 154 missing mc_ueid or mc_udid ID 154 missing or bad map name 148 missing or bad selector name 149 missing placeholder 155 parameter missing from function 147 receive thread cannot start 154 response parsing 149 returning for queries 155 selector set file name 151 selector set file syntax 149 selector set loop 155 starting receive thread 151 success message 155 supported library 156 timeout expiration 155 unable to create event message 147 unable to create object 151 unable to open file 151 unknown message type 156 unsupported query 152 unsupported structure 152 UseLocks setting 154 errors (core) bmcii_startserver function 161 bmcii_stopserver function 161 communications errors 157 connecting 160 connection failure 158 ConnectionPortRange parameter 159 full buffer 160 inbound communication module 158 invalid encryption key 159 invalid host name 158 invalid IP address 158 invalid or misspelled paths 159 memory allocation 160 message destination not available 160 META_FAIL_IF_UNCONNECTED metaslot 160 no error 161 outbound communication module 158 port access 160 port range 159 starting server mode 161 stopping server mode 161 TCP/IP not available 161 timeout expiration 161 trace configuration file 162 errors (Web services) closing connection 142 connecting to cell 141 creating message type 142 creating messages 142 failed to get query result 144 getting selector names 142 incorrect date in query 143 invalid client context ID 142 invalid query handle 143 invalid start index 143 query call 142 Index 177

178 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z query handle cleanup 143 receiving empty event 142 sending message to cell 142 setting slot name 142 setting slot name-value 142 unknown query result 143 event classes error 149 unable to create message 147 event dispatcher 165 custom 166 dispatch operations 166 EventListener.wsdl 166 messages 167 operations 168 event handle, missing 154 event listener 96 event listener libraries custom 165 event dispatcher 96 event listener server 96, 97 event listener server customizing 166 EventListener.wsdl 166 service element 171 event propagation defining rules in KB 45 example rule 48 Propagate policy 43 state change events 45 subscription requests 89 WSCELL event listener 43, 45, 89 EventListener.wsdl dispatch operations 165 executable files imserv 60 F FailOnMissingSlot message selector header parameter 112 failure matching 112 selection 112 formatting %, using in message selectors 116 error in map set file 148 error in selector set file 149 message selectors and message selector sets 110 missing BAROC END statement error 150 FormatVersion parameter, in message selector set header 111 functions $ClassName 114 $doselector 115 $Format 116 $function_name 114 G $GmtTime 116 $HostName 114 $LocalTime 116 $slotmissing 116 $slotpresent 115 $TimeT 116 in message selectors 113 slot.slotname 114 guaranteed event delivery 89 H high availability cells configuration 51 configuration with BMC Performance Manager 54 guidelines 53 implementation scenarios 52 host name, invalid or incorrect 147 host names, specifying in message selectors 114 http-server.xml 56 I iiws.conf file, editing 136 iiws.conf, configuration parameters 124 iiws.selector file 120 iiws.trace file 138 modifying 139 restarting the server 139 Impact Integration C APIs relation to Web services 105 ImpactManager.wsdl client proxy code 75 introduced 16 source-code generator 75 installation AIX runtime libraries 26 compatible cells 22 compatible OpenSSL 23 compatible toolkits 23 directory contents 29 environment variables 31 Java Runtime Environment 25 Linux, Solaris, HP-UX, AIX (console) 29 Linux, Solaris, HP-UX, AIX (X Window System) 27 netstat command 25 port verification 25 prerequisite checks 25 supported operating systems 22 tested compilers 23 uninstalling BMC Impact Integration Developer s Kit Web Services Server Developer Guide

179 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z L libraries Basic C API runtime 16 custom event listener 165 wrong map or selector set support 156 listenercfg.xml file 173 locale directory 30 localization, LocaleConfigFile 135 loops $doselector error 155 error in map set 153 error in selector set 155 M map header, bad or missing header 148 map set files name error 151 syntax error 148 map sets disabled 153 invalid parameters 152 library support error 156 loop error 153 maps disabled 153 missing or bad name 148 syntax error 148 MaxResponseEventListSize parameter 57 mc_udid ID, missing 154 mc_ueid ID, missing 154 mcell.dir adding WSCELL event listener 42 configuration 38 description 17, 139 directory location 30 editing 139 location 18 WSCELL event listener 18 mcell.dir file 151 memory allocation error 160 failure allocating 154 leaks 160 message buffer capacity 126 message propagation MessageBufferKeepSent parameter 126 MessageBufferKeepWait parameter 126 MessageBufferReconnectInterval parameter 127 MessageBufferResendCount parameter 127 MessageBufferSize parameter 126 parameters list 126 message selectors characteristics 107 content 113 embedding 115 embedding with $doselector 108 file, characteristics 107 formatting 110 header requirement 112 header sample 113 message selector set header 110 name 112 operators 117 parameters, header 112 parameters, set header 111 set header requirement 110 set header sample 111 sets, description 108 sets, formatting 110 sets, headers 110 sets, naming 108 slots, missing 112 syntax rules 107 time, specifying settings 116 message type error 148 unkown 156 MessageBufferKeepSent 126 MessageBufferKeepSent configuration parameter 126 MessageBufferKeepWait configuration parameter 126 MessageBufferReconnectInterval configuration parameter description 127 MessageBufferResendCount configuration parameter 127 MessageBufferSize configuration parameter description 126 MessageBufferSize parameter, modifying 160 messages bad message type 148 buffering 160 corrupt buffer error 150 corruption or null parameter 148 error when modifying 154 full buffer 160 invalid connection handle 159 invalid or corrupted 153 missing class name 147 unable to create 147 unknown message type 156 mutex error 148 N namespaces declared in EventListener.wsdl 166 netstat command 25 non-reliable subscription 91 Index 179

180 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z O OpenSSL supported version 23 operations client proxy code 78 sequence for polling client 92 sequence for sending events 82 P parameters ChangeDate 111 ClientSourceIP 125 ClientSourcePort 125 configuration file 124 ConnectionPortRange 126 ConnectionPortReuse 126 ConnectionSetupTimeOut 125 Description 111 DropAcks 130 DumpIncoming 133 Enable 111, 112 EnableRecvPersist 129 Encryption 126 FailOnMissingSlot 112 FormatVersion 111 KeepRecvPersisted 129 LocaleConfigFile 135 MaxSleep 134 message selector set header list 111 MessageBufferKeepWait 126 MessageBufferReconnectInterval 127 MessageBufferResendCount 127 MessageBufferSize 126 MinClientSleep 133 MinSleep 134 PersistencyCleanupGarbageThreshold 128 PersistencyCleanupSizeThreshold 128 PersistencyDisconnectRemoveMessages 128 PersistencyEnabled 128 PersistencyFileName 128 PersistencyLevel 128 ReceiveBufferDir 129 SelectorHeader 112 SelectorSetName 111 ServerAllInterfaces 135 ServerDirectoryName 124 substitution parameters 138 TraceConfigFileName 131 TraceDefaultFileName 131 TraceFileAppend 132 TraceFileHistory 132 TraceFileSize 132 TraceSrc 131 UniqueIdFile 135 UseMemWatch 133 Version 111 parsing error 149 paths environment variables 31, 32 invalid or misspelled 159 PersistencyCleanupGarbageThreshold configuration parameter 128 PersistencyCleanupSizeThreshold configuration parameter 128 PersistencyDisconnectRemoveMessages configuration parameter 128 PersistencyEnabled configuration parameter 128 PersistencyFileName configuration parameters 128 PersistencyLevel configuration parameter description 128 polling call bmciiws_getevents 92 polling interface 94 callback URL 90, 97 event queue 92 list of operations 92 MaxResponseEventListSize parameter 57 subscription requests 90, 96 unsubscribing, effects of 93 ports BMC Impact Integration Web Services Server 55 changing 56, 57 invalid or incorrect 147 invalid range 159 port range error 159 privilege error 160 use by other applications 160 Web services server 82 WSCELL event listener 18, 55 printf function 116 product support 3 Propagate policy 43 propagate. See event propagation publish-subscribe interface callback URL 91, 97 callbacks 95 client 166 event dispatcher 96 event listener server 96 subscription requests 95, 96 Q queries broken connection 155 class definition 83 description 82 failed connection 155 processing 83 returning replies BMC Impact Integration Developer s Kit Web Services Server Developer Guide

181 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z R service model 83 unsupported 152 receive thread cannot start 154 error 151 resources memory allocation error 160 memory allocation failure 154 memory insufficient error 147 S security certificate generation 66 general guidelines 66 responsibility of client developer 66 SSL 65 Web services server support 65 selector set files loop error 155 name error 151 syntax error 149 selector sets invalid parameters 152 library support error 156 loop error 155 SelectorName message selector header parameter 112 selectors iiws.selector file 120 in subscription requests 90, 107 missing or bad name 149 overview 106 syntax error 149 with client context ID 97 selectorset_name.message selector file 108 SelectorSetName message selector set header parameter 111 send request processing 82 server. See BMC Impact Integration Web Services Server ServerAllInterfaces configuration parameter 135 servercfg.xml file parameters 57 updating 57 servercfg.xml file security parameters 70 ServerDirectoryName configuration parameter 124 service model queries 83 slot.slotname function 114 slots bad name error 150 bad slot value error 150 bad value error 150 do not exist 154 empty string for name 150 in message selectors 113 missing from message selectors 112 null 150 selecting, by value 114 SOAP (Simple Object Access Protocol) 15 SOAP messaging 17 sockets, initialization error 150 source-code generator client proxy code 75 compiling ImpactManager.wsdl 75 state change events 45 strftime 116 strings empty value in slot 150 malformed BAROC 147 structures, unsupported 152 subscription requests bmciiws_subscribe 96 callback URL 90, 97 multiple 96 overwriting by server 97, 98 parameters 90 polling interface 90, 96 publish-subscribe interface 96 selectors 90 uniqueness 97 substitution parameters 138 support, customer 3 syntax bad or missing map header 148 bad or missing selector header 149 bad slot name error 150 bad slot value error 150 error in selector set file 149 map set file error 148 selector set file error 149 Systinet WASP server 16 T TCP/IP, invalid IP address error 158 technical support 3 time, using in message selectors 116 time_t, in message selector files 116 timeout, expiration error 155, 161 toolkits Axis 23 client proxy code 81 OpenSSL 23 stub generation 17 Visual C#.NET WASP Server for C++ 23 trace file error 162 Index 181

182 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Trace parameter 131 TraceConfigFileName configuration parameter 131 TraceConfigFileName parameter 131 TraceDefaultFileName configuration parameter 131 TraceFileAppend configuration parameter 132 TraceFileHistory configuration parameter 132 TraceFileSize configuration parameter 132 TraceSrc configuration parameter 131 TraceSrc parameter 131 tracing parameters in BMC II C APIs configuration files 131 TraceConfigFileName parameter 131 TraceDefaultFileName parameter 131 TraceFileAppend parameter 132 TraceFileHistory parameter 132 TraceFileSize parameter 132 TraceSrc parameter 131 translation class names, specifying 114 host names, specifying 114 transport mechanism 15 updating listenercfg.xml file with security 173 Web services server event dispatcher 96 invalid name error 153 overwriting subscription requests 97, 98 security implementation 65 Web services. See BMC Impact Integration Web Services WSCELL event listener adding to mcell.dir 42 description 18 event propagation 43, 45 port 18 WSDL (Web Services Description Language) defined 15 EventListener.wsdl 165 ImpactManager.wsdl 16 U uninstalling BMC Impact Integration Web Services Server 34 uniqueid.dat 135 UniqueIdFile configuration parameter 135 UseLocks parameter, setting error 154 using substitution parameters 138 V Version, message selector set header parameter 111 W Wasp library files 16 Web service client client code samples 30 compatible toolkits 17 interface types 89 polling interface 94 queries 83 Web services client callbacks 95 client proxy code 78 event listener server 96 multiple subscription requests 96 planning considerations 74 polling interface 92 programming language 74 sending events and data 81 summary of steps 75 types BMC Impact Integration Developer s Kit Web Services Server Developer Guide

183 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Glossary Note: The definitions of terms common to web services are derived from the W3C working draft Web Services Glossary at Copyright 2004 W3C (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply. The definition of terms common to event distribution systems are derived from the online computing dictionaries at WhatIs.com and Foldoc.org. $MCELL_HOME The UNIX platform environment variable that defines the home directory in which BMC Impact Manager product files reside. (It is also designated as installdirectory/...) Use this environment variable to find all product executables and configuration files. See also mcell.dir file and WSCELL. %MCELL_ HOME% The Windows platform environment variable that defines the home directory in which BMC Impact Manager product files reside. (It is also designated as drive:\installdirectory.) Use this environment variable to find all product executables and configuration files. See also mcell.dir file and WSCELL..load file A file that specifies the order in which a directory s files are to be loaded and read by a BMC Impact Manager instance..map file See adapter map file..mrl file A file that contains rule and collector definitions written in the Master Rule Language (MRL). Event and service management processing rules and collectors are stored in.mrl files and in compiled.wic files. /etc/mcell On UNIX platforms, the directory that contains the setup_env.sh and setup_env.csh scripts, which set the environment variables used by the product software. Glossary 183

184 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z A Acknowledge The event operation action that acknowledges the existence of an event. See also local action. Acknowledged status The event status that results from an Acknowledge event operation action; it means that an operator has acknowledged the event's existence. action 1. Generally, a procedure that is invoked to produce a specific result. It can be a script or a call to an executable that is invoked automatically in response to an event, or it can be a manual intervention. Actions can be scheduled or immediately invoked locally or remotely. 2. In BMC Impact Manager, an executable that can be run by a cell. Actions are called in an Execute rule. Users can request the execution of actions in the BMC Impact Explorer. See also local action. adapter A background process that audits data from various sources, evaluates it for specific conditions, and creates the corresponding events. Adapters also transform event data into the format understood by BMC Impact Manager. adapter instance An adapter that is defined in the adapter configuration file. The definition is given a name and specifies an adapter type, such as a log file adapter. adapter map file A text file that defines the translation of a message between one event format and another. It is also known as a.map file. administrator The person responsible for administrative tasks within the product. alias See service component alias. API See Application Program Interface (API). Application Program Interface (API) A set of externalized functions that allow interaction with an application. asset An object instance in the BMC Atrium Configuration Management Database (BMC Atrium CMDB). There are two types of assets in the BMC Atrium CMDB: non-service components, such 184 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

185 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z as desks and other non-it physical assets, and service components which are components that participate in the delivery of enterprise services. asynchronous web services A message exchange pattern in which the sender and receive do not have to communicate at the same time in a precise sequence. For example, a request message can be stored and delivered at a later time. Neither sender nor receiver depends on the immediate completion of the request. Contrast with synchronous web services. attribute A characteristic or property of an object, such as a common data model service model component class. An attribute may contain a value. B BAROC Language Basic Recorder of Objects in C. A structured language used to create and modify class definitions. A class definition is similar to a structure in the C programming language. The elements in a structure are called slots. bindings In Web Services Description Language, the method that defines how SOAP messages are exchanged through an underlying protocol. They are a formal set of rules for carrying a SOAP message over a transport mechanism. In BMC II Web Services, the messages are communicated via SOAP over HTTP. See also SOAP encoding. BMC Atrium CMDB Common Data Model (BMC Atrium CMDB CDM) An extensible schema that provides a unified representation of configuration items and their relationships to each other. It is used to store asset data (such as hardware information, service management information, and people information) and to provide a mechanism for linking that information to provide a complete view of how all assets are connected and can affect each other. BMC Atrium CMDB Reconciliation Engine The BMC Atrium CMDB application used to merge data from multiple sources, such as topology or configuration discovery, into a consistent dataset. BMC Atrium Configuration Management Database (BMC Atrium CMDB) The database application that is the common datastore for asset, configuration management, and service model data in BMC Business Service Management products. It enables BMC products to share IT management and monitoring data and perform service management. BMC Desktop Status Indicator (BMC DSI) An icon that appears in the desktop system tray of a computer to show the current status of an object being monitored by BMC Impact Portal. To view the status page of the monitored object, you double-click the icon. Glossary 185

186 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z BMC Event Manager (BMC EM) A real-time event management product license package that provides event management, including event collection, correlation, enrichment, and integration. It enables IT operations staff to focus the proper resources on resolving the most critical events. BMC II C APIs A collection of programming functions written in the C programming language that are designed to build applications which integrate with the BMC Impact Manager product by sharing events and data. The BMC II Web Services package includes the runtime library files of the BMC II C APIs. BMC II See BMC Impact Integration (BMC II) product. BMC IM See BMC Impact Manager (BMC IM). BMC Impact Explorer (BMC IX) A console with which you can connect to any number of instances of BMC Impact Managers, examine the events stored in them, and perform event and service management activities. BMC Impact Integration (BMC II) product An interface that enables the synchronized, bidirectional flow of events and data between a BMC Impact Manager instance or instances and another BMC Software product or a specific third-party product. BMC Impact Integration (BMC II) Web Services A web services client developer package that includes a built-in web service, a server, and a sample client. It enables web service client developers to build a client that can connect to and exchange events with the BMC Impact Manager network. BMC Impact Manager (BMC IM) The BMC Impact product that provides automated event and service-impact management. It runs as a service on supported Windows platforms and as a daemon on UNIX platforms, and can be distributed throughout a networked enterprise and connected in various topologies to support IT goals. BMC Impact Manager instance An installation of the BMC Impact Manager product on a host computer. Compare with cell. BMC Impact Publishing Server The BMC Impact Portal service or daemon that obtains the service model from the BMC Atrium CMDB and publishes (distributes) it to the designated service impact management cell or cells. BMC Impact Portal The BMC Portal console module that you use to monitor the status of business services and their components. See also console module. 186 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

187 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z BMC Impact Reporting The BMC Impact Solutions component that you use to create and view long-term reports. BMC Portal A BMC licensed product that consists of the BMC Portal Server (infrastructure) and console modules, each of which deliver specific Business Service Management (BSM) functionality. The BMC Impact Portal is an example of a console module. BMC Reporting Foundation The base component on which BMC Software reporting systems and solutions are built. BMC Service Impact Manager (BMC SIM) A real-time service impact management product license package that provides technologies for both service impact and event management (SIEM). BMC SIM identifies related applications and the underlying systems and databases of any software or infrastructure component and ties systems-level monitoring to the supported business services, enabling IT personnel to respond quickly to problems that threaten the delivery of business services. Business Service Management (BSM) A dynamic method for connecting key business services to the IT systems that manage them. BSM enables users to understand and predict how technology changes will affect their business, and how changes in the business affect the IT infrastructure. C callback interface An abstract connection between the BMC II Web Services client and the event listener server component that resides on it. The callback interface enables the event listener to execute code on the client. The client registers callbacks with the event listener. When the event listener receives an event, it dispatches it to a callback. Callbacks are implemented for BMC II Web Services clients that use the publish-subscribe model, not polling, to retrieve events from the BMC Impact Manager product network. See also push interface. Contrast with polling interface. callback URL The address or uniform resource locator of the event listener server that resides on the BMC II Web Services client. At runtime, the event listener server reads the callback URL from a configuration file that is specific to your web services toolkit. cell The event processing engine that collects, processes, and stores events within a BMC Impact Manager instance. Each cell uses the information in the associated Knowledge Base to identify the type of events to accept and how to process and distribute them. See also mcell.dir file. Glossary 187

188 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z class 1. A data storage element. In database terms, it relates to a table in a database or a form in the Remedy AR System. 2. In BMC Impact Manager, a BAROC-language data structure that defines a type of object used in BMC Impact Manager. A BAROC class is made up of data fields, called slots, that define its properties. client context ID A string descriptor that identifies the name of the web services client. BMC II Web Services Server uses the client context ID with the selector name to determine which client receives events. command line interface (CLI) A user interface in which you issue commands one at a time on a command line for automation or immediate execution. In BMC Impact Manager, you use the CLI in conjunction with a graphical user interface (GUI) to operate the product. component A logical or physical asset that is stored in the BMC Atrium CMDB. There are two types of assets in the BMC Atrium CMDB: non-service components, such as desks and other non-it physical assets, and service components, which are components that participate in the delivery of business services. component instance A named component that represents an actual IT resource. condition A prerequisite that must exist or a qualification that must be met for selection or processing to take place, such as individual slot-value tests. console module A product that plugs into the BMC Portal. consumer An entity that makes use of ( consumes ) a web service or, in an event distribution system, a programming object that subscribes to specific events. Contrast with provider. D data class A BAROC class that is a child of the base event class, DATA, and that defines a type of data. datastore A central place in which an aggregation of data is kept and maintained in an organized way. 188 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

189 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z data type A representation of an abstract concept such as integer, time, date, and so forth. A data type consists of a literal representation, valid values, and defining characteristics. In XML schema, it can be built-in or user-derived. The types element of the Web Services Description Language identifies the data types available to the web service. draft service model A working version of the service model that contains both published and unpublished elements. duplicate event A subsequent occurrence of an event that has already been received, such as the second or later notification that a component is down. An event that has matching values for all the slots defined with the dup_detect=yes facet in the event class definition.you can use Regulate rules to detect and count duplicate events. See also facet. dynamic collector A special type of collector that, in response to events, can add or remove event collectors from the cell during runtime. dynamic data Contextual reference data that is stored in a table in the repository (mc.db) and that can be updated during runtime. Administrators can use and manipulate dynamic data in the BMC Impact Manager Administration View. E EnableTrace parameter A configurable parameter in the BMC II Web Services Server that, when set to true, activates the server logging facility. encryption key The seed encryption key. If the destination BMC Impact Manager or BMC Impact Integration product has a key value, all clients must encrypt their communications using the same key value. endpoint A specific location (uniform resource identifier) for accessing a web service using a specific protocol and data format. See also service. enrichment 1. The process of adding to or modifying the original event data to enhance it for problem management, service management, correlation, automation, notification, or reporting functions. 2. A type of policy. Glossary 189

190 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z event A structured message passed to and from cells in a BMC Impact environment. It is an instance of an event class. event class 1. A BAROC class that is a child of the base event class, CORE_EVENT, and that defines a type of event. 2. A category of events that you can create as a child of the base event class, CORE_EVENT, according to how you want the events to be handled by an event manager and what actions you want to be taken when the event occurs. Event classes may be inherited from parent objects, depending on the specific product. Event classes are inherited from parent objects in BMC Impact Manager. event collector An event grouping whose content is defined by its collector rule. Event collectors are displayed in the BMC Impact Explorer and are defined in the BMC Impact Manager Knowledge Base. See also event collector rule. event collector rule A type of rule in the Knowledge Base that defines how events from a cell are organized and presented in the BMC Impact Explorer. Collector rules are written in Master Rule Language (MRL). Event Condition Formula (ECF) The section of an MRL rule definition that specifies the conditions that an incoming event must meet to trigger evaluation of the rule during processing. For example: APP_MISSING_PROCESSES where [hostname: == red1,sub_origin: contains System ] is an ECF. See Master Rule Language (MRL). event dispatcher A software mechanism that resides on the BMC II Web Services Server. Functioning like a client, it dispatches events in the form of one-way request messages to the event listener server that resides on the BMC II Web Services client. It is used in publish-subscribe client implementations. See also event listener utility, event listener server, and event notification service. event listener utility A short-hand reference that describes the main components of an event listener library: the event dispatcher and the event listener server. Refers to publish-subscribe client implementations. See also event dispatcher, event listener server, and event notification service. event listener server A software mechanism that resides on the BMC II Web Services client. The client registers callbacks on the event listener server. The server listens for events that are sent from the event dispatcher residing on the BMC II Web Services Server. When an event is received, the server dispatches it to a callback in the list of callbacks that it maintains. Used in publish-subscribe 190 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

191 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z client implementations. See also event dispatcher, event listener utility, and event notification service. event management The collection and correlation of events across an enterprise to enable IT operations to focus the proper resources on the most critical events. event management policy One of several generic rule types that perform actions against events that meet selection criteria specified in an associated event selector. Unlike manually written rules, event policies are defined interactively using the Event Management Policy Editor in the BMC Impact Explorer. event notification service A BMC Software implementation of the Systinet WASP Server for C++ Toolkit event listener libraries. It is built into the BMC II Web Services package. The event listener libraries handle asynchronous event publication and subscription, and they are used in web services publishsubscribe client implementations. To use the built-in event notification service, you must use the Systinet WASP Server for C++ Toolkit and write the client code in the C++ or Java programming language. See also event dispatcher, event listener utility, and event listener server. event propagation The act of forwarding events and maintaining their synchronization among multiple BMC Impact Manager instances (cells). event selector The filtering mechanism associated with an event policy that selects the events against which the event policy performs actions. An event selector contains one or more event selection criteria. Event selectors are defined interactively by using the BMC Impact Explorer. An event policy can use one or more event selectors. EventListener.wsdl file The Web Services Description Language file that describes the event dispatch service which you can access to build your custom event listener utility that is specific to your web services toolkit. See also Web Services Description Language (WSDL). Execute rule An event-processing rule that performs actions when a slot value changes in its event repository. Execute rules are evaluated during the Execute phase of event processing. Often, the resulting actions are internal actions, but you can use the execute primitive in a rule to call an external executable. Glossary 191

192 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z F facet In the BMC Impact Manager product, a specific attribute of a class slot that either controls the values that the slot can have or controls aspects of a class instance s processing. In XML, a single defining aspect of a value for a data type. It is characterized as fundamental, which defines the data type, or constraining, which restricts the values of a data type. See also data type. fault message In Web Services Description Language, a SOAP (Simple Object Access Protocol) message that contains fault information related to a set of SOAP communication messages. The fault message indicates the reason why the SOAP communication failed. field See attribute. Filter rule An event-processing rule that determines whether a specific type of event should be passed as it is, subjected to further processing, or discarded during the Filter phase. function Code that executes an operation in a cell and returns a value. A function can be used as an expression within a rule or a policy and in alias formulas. G gateway An integration that receives connections and events from BMC Impact Manager instances. A gateway can use a custom message format or custom message content (different slots). gateway.export file A special file that controls the propagation and synchronization of events to a BMC Impact Manager Integration product. The file is in the installdirectory/etc/ directory on UNIX platforms and in the drive:\installdirectory\etc\ directory on supported Windows platforms. H heartbeat 1. A periodic message sent between communicating objects to inform each object that the other is still active and accessible. 2. In BMC Impact Manager, a dynamic data object sent by a cell to monitor other cells to verify that they remain active and accessible. 192 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

193 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z heartbeat interval The time between heartbeats; the period of the heartbeat. I impact An assessed measure of the effect that an incident, fault, or other change will or may have on business operations or service levels. ImpactManager.wsdl The Web Services Description Language file that describes BMC II Web Services and enables you to access its operations. See also Web Services Description Language (WSDL). impact event An event whose status is used in computing the status of its associated service component. By default, the status of all events associated with a service component are used to compute its status. However, you can exclude events if you wish. impact propagation The effect of an impact to a providing service component (provider) on the service components that use its services (consumers) as defined by an impact relationship. See also impact relationship. impact relationship A relationship between two service components in a service infrastructure in which a consumer component depends on a provider component to deliver some needed resource to it. Changes in status of the provider affect (has an impact on) the status of the consumer component. imserv The name of the executable that launches the BMC II Web Services Server. By default, it is located in the drive:\installdirectory\bin or installdirectory/bin directory. instance 1. A specific object with specific attributes or characteristics that distinguish it from other items (members) of its class or type. 2. In BMC Impact Manager, an object that has specific attribute values and that was created using a class definition. integration product See BMC Impact Integration (BMC II) product. K kb directory The default directory in which a BMC Impact Manager Knowledge Base is located. The directory and basic product definitions are created during installation. Glossary 193

194 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z key slot A slot whose value is compared during searches. Knowledge Base (KB) A collection of information that forms the intelligence of a BMC Impact Manager instance and enables it to process events and perform service-impact-management activities. This information includes event class definitions, Service-Model component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules. L load file See.load file. local action An executable that you can run directly from the BMC Impact Manager. Local actions are written in XML and are stored in the OS-specific subdirectory of the bin directory of the BMC Impact Manager cell Knowledge Base. M manifest.kb A central locator file that specifies the locations of the directories that make up a Knowledge Base. The manifest.kb file is used by the compiler to load the Knowledge Base source files for compilation. Master Rule Language (MRL) A compact, declarative language used to define rules and collectors for processing and organizing events. Uncompiled rule and collector source files have a.mrl file extension. MaxEventQueueSize parameter A configurable parameter for the BMC II Web Services Server that determines the maximum number of events that the server will cache in memory. This value is defined for the server and is not dependent on the number of connected clients or subscription calls. It is defined in the servercfg.xml file and is implemented for client polling requests. MaxResponseEventListSize parameter A configurable parameter for the BMC II Web Services Server that defines the maximum number of events that the server returns per polling request. This value can be different from the number of events that the client requests. It is defined in the servercfg.xml file. mccomp The BMC Impact Manager rules compiler. Rules are written in the Master Rule Language (MRL). The platform-independent compiler converts them to byte code that the cell can read and process. 194 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

195 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z mcell.conf file The configuration file that contains configuration options for a BMC Impact Manager instance (cell). It is in the installdirectory/etc/ directory on UNIX platforms and in the drive:\installdirectory\etc\ directory on supported Windows platforms. mcell.dir file The file that lists the cells to which a product component can connect and communicate. The information for each cell includes: its name, its encryption key, and its host name and port number. This file is in the installdirectory/etc/ directory on UNIX platforms and in the drive:\installdirectory\etc\ directory on supported Windows platforms. mcell.modify file The file that lists the slots that affect the mc_modification_date slot. When a specified slot is modified, the time stamp of the modification is reset in the mc_modification_date slot, so that slot is listed in mcell.modify. mcell.trace file The configuration file that specifies the trace information about a BMC Impact Manager (cell) that should be recorded and the location to which it is written. It is in installdirectory/etc/ directory on UNIX platforms and in the drive:\installdirectory\etc\ directory on supported Windows platforms..mrl file A file that contains rule and collector definitions written in the Master Rule Language (MRL). Event and service management processing rules and collectors are stored in.mrl files and in compiled.wic files. mc_udid See universal data identifier (mc_udid). N namespace In XML, a collection of element and attribute names and values that is stored in an XML document and accessed by its uniform resource identifier. The XML file that accesses the uniform resource identifier can incorporate the information that is stored in the document. node A BMC Impact Manager instance that can receive only events originating on the local host system. non-local action A user-initiated action that does not execute on the user console host machine. normalization The process of homogenizing event data into a common event format so that a standard set of event data is collected and reported regardless of the event source. Glossary 195

196 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z notification 1. A message, either detailed or concise, that contains information about a condition that triggered an alert state on a monitored element. An message or SNMP trap that is sent when the program detects a problem that triggers an alert. O 2. A type of policy. object class In BMC Impact Solutions, a data structure that defines a type of object. An object class can be a BAROC-language data structure in a BMC Impact Manager cell Knowledge Base or a Common Data Model (CDM) data structure in the BMC Configuration Management Database. A class is made up of data fields, called attributes (slots) that define its properties. See also event class, object, and object hierarchy. operation In Web Services Description Language, a set of messages related to a single web service action. P phase (rule) A specific stage of event processing. There are eight sequential phases to event processing and two nonsequential phases, each with a corresponding rule type. policy class A BAROC class that is a child of the base data class POLICY and that defines a type of policy. policy instance A specific implementation of any of the types of event management policies. For example, you could have an instance of a blackout policy that defined blackout periods for holidays and another instance of the same policy that defined blackout periods for monthly maintenance. polling interface An abstract connection between a BMC II Web Services client and the server in which the client retrieves events from an event queue by invoking polling calls. See also pull interface. Contrast with callback interface. port A specific communication channel in TCP/IP networking. Ports are identified by numbers. BMC Impact Manager communicates using the ports specified during installation. port type In Web Services Description Language, a logical grouping of operations and their messages. It defines the public entry point for client applications. 196 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

197 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z porting The process of translating or converting software to run in a different operating environment. Propagate rule An event-processing rule that is used to forward events to other BMC Impact Managers in the managed domain. Propagate rules are evaluated during the Propagate phase of event processing. propagated event An event that is forwarded from one cell to another cell or to an Integration product during the Propagate phase of event processing. propagation See event propagation. provider An entity that provides a service, such as a web service, or, in an event distribution system, a programming object that publishes events. Contrast with consumer. publish In an event distribution system, a provider action of making events and data available by sending messages to a space or node without specifying a specific destination. Contrast with subscribe. pull interface A processing model in which the event consumer (the BMC II Web Services client) controls the event flow by requesting events from the provider through polling calls. The BMC II Web Services Server collects events in an event queue and waits for the client to initiate the request for events. See also polling interface. Contrast with push interface. push interface A processing model in which the event provider (the BMC II Web Services Server) controls the pace of the event flow through the implementation of an event listener utility and callbacks. The message consumer (the BMC II Web Services client) waits to receive events that are published by the event provider (the BMC II Web Services Server). See also callback interface. Contrast with pull interface. R Regulate rule An event processing rule that processes repetitive (duplicate) events or events that occur with a specified frequency. With a Regulate rule, you can create a new event based on the detection of repetitive or frequent events. See also Regulate phase. repository The storage facility in which BMC Impact Manager event information is stored. Glossary 197

198 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z root cause analysis The process of monitoring events and correlating event data to identify the true cause of a problem. rule A conditional statement that, if determined to be true, executes actions. The cell evaluates events by comparing each event to a series of rules during event processing. Rules are grouped in phases that are processed one by one. The order in which rules are evaluated during a particular phase is based on the order in which they were loaded. When all the rules in one phase are evaluated, the cell moves to the next phase. S selector A set of defining criteria that is used to match events. The criteria are defined in a text file with the file name extension of.selector. Within the file, the defining criteria are enclosed within braces. See also web services subscription selector. servercfg.xml file The BMC II Web Services Server configuration file. It contains parameters, some of which are read at runtime, that determine the port number, event queue size, server log file, and other information. It is located in installdirectory/conf or drive:\installdirectory\conf. service In Web Services Description Language, a collection of endpoints. Each endpoint indicates a specific location for accessing a service using a specific protocol and data format. See also endpoint. service component alias A name that is assigned to a service component instance and used in associating an event type with the component instance. You add an alias to a service component instance s definition in the Service Model Editor. A service component instance can have several different aliases to enable different event types to be associated with it. slot An attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instance s processing. A class that is a subclass to another class inherits all the slots of the parent class. SOAP encoding A set of rules for encoding data to conform to the SOAP data model of mapping non-xml based data to an XML representation. The encoding can be used to transmit data in SOAP message format. See also bindings. 198 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

199 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z source-code generator A software tool that creates source code (client stubs) in a specified programming language from a Web Services Description Language file for a web service. See also stub. SSL Secure Sockets Layer. A security protocol that manages the security of messages communicated on the Web. The Secure Sockets Layer lies between the transport mechanism layer (typically HTTP) and the underlying TCP layer. See also transport mechanism. state change event A generated event type that records changes in a component s status. State change events never participate in component status computation. stub A small program routine that acts as a substitute for a larger program routine. The stub accepts requests from one program and forwards them to another. The stub accepts the responses from the receiving program and passes them back to the program that made the request. In BMC II Web Services, you use a source-code generator to generate client stubs from the Web Services Description Language File. See also source-code generator. subscribe In an event distribution system, a consumer action of registering to receive (subscribe to) specified events. Contrast with publish. subscription table A data table within the BMC II Web Services Server in which client context IDs are matched with selector names. Each subscription call invoked by a BMC II Web Services client contains a context ID that identifies the client and a selector name that indicates the types of events it requests. The subscription table enables the BMC II Web Services Server to send the requested events to the corresponding client. synchronous web services A message exchange pattern in which the sender and receiver must interact in a precise sequence. For example, a sender submits a request message and cannot continue processing until it receives a response. Contrast with asynchronous web services. T transport mechanism An upper layer communications protocol for opening and closing communication requests across the Web. The transport mechanism runs on top of the underlying TCP/IP communication language. In web services, HTTP (Hypertext Transfer Protocol) is a standard transport mechanism for SOAP-encoded messages and is used by BMC II Web Services. See also SSL. Glossary 199

200 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z U UDDI Universal Description, Discovery, and Integration. A Web-based information registry where businesses can register information about the web services they offer. web services consumers can discover and invoke the web service from the registry. The registration of web service instances in UDDI registries is optional. BMC II Web Services is not registered in UDDI. universal data identifier (mc_udid) A unique, system-generated value used to identify a specific service component instance. Each service component must have a value for the mc_udid attribute (slot). One use of the universal data identifier is in associating aliases to a service component instance. W WASP Server for C++ A Systinet product that is a collection of runtime libraries which BMC II Web Services has adapted for use in its implementation of the BMC II Web Services Server, specifically the event listener libraries. Web Services Description Language (WSDL) The standard XML-based language for describing web service interfaces and enabling consumers to access the web service electronically. A typical WSDL file is divided into sections that define data types, messages, operations, bindings, and services. The file exposes the type of data that is transmitted, the message pattern between parties, the function calls and parameters that can be invoked, the way each function call is communicated electronically, and the specific port address from which the service can be accessed. See also EventListener.wsdl file and imserv. web services subscription selector A special usage of a selector. A selector set used to match incoming messages that have propagated from BMC Impact Manager product instances. This selector makes the matching messages available to the subscribing web services client or clients. See also selector. When clause A part of MRL rule syntax for Abstract, Correlate, Execute, Propagate, and Timer rules. Events must first meet the selection criteria in the rule before the When clause is evaluated. Changes to slot values cause When clauses to be re-evaluated. 200 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

201 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z WSCELL A message receiver for the BMC II Web Services Server that functions as a listener. It accept connections from BMC Impact Manager instances at default port number It receives events and messages from BMC Impact Manager instances and stores them in a buffer. The WSCELL entry is defined in the mcell.dir file of the BMC II Web Services Server. Each instance of the BMC II Web Services Server must have its unique WSCELL entry. To connect with the BMC Impact Manager network, you must also enter the WSCELL information in the mcell.dir file of BMC Impact Manager instance to which you are connecting. See also mcell.dir file. Glossary 201

202 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 202 BMC Impact Integration Developer s Kit Web Services Server Developer Guide

203 BMC SOFTWARE SDK LICENSE AGREEMENT BY OPENING THE PACKAGE, INSTALLING, PRESSING AGREE OR YES OR USING THE BMC MODULES, THE ENTITY OR INDIVIDUAL ENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS, IF YOU DO NOT AGREE WITH ANY OF THESE TERMS, DO NOT INSTALL OR USE THE BMC MODULES AND PROMPTLY RETURN THE BMC MODULES TO BMC. IF YOU REJECT THIS AGREEMENT YOU WILL NOT ACQUIRE ANY LICENSE TO USE THE BMC MODULES. SCOPE OF AGREEMENT. This Agreement is between the entity or individual entering into this Agreement ( You ) and BMC Software, Inc. ( BMC ). This Agreement governs Your use of the BMC Modules, unless You agreed to a web-based license agreement with BMC when ordering the BMC Modules, in which case that web-based license agreement governs the use of the BMC Modules. As used herein, Complementary Product means any product of You that embeds or is dependent for execution upon a BMC Module. LICENSE. BMC grants You a non-exclusive, non-transferable, personal license ( License ) for one person (the Developer ) (a) to copy and operate the BMC Modules for the sole purpose of designing, developing and testing Complementary Products, provided that You acknowledge and agree that the right of embedding does not include a right of distribution, and (b) to copy and operate Complementary Products (including any BMC Modules embedded therein) solely for Your internal production purposes. You may not and agree not to: (i) copy the BMC Modules or the Complementary Products except as expressly permitted in the immediately foregoing sentence, (ii) distribute, resell, rent or lease the BMC Modules or the Complementary Products, (iii) use the BMC Modules for production purposes except as expressly permitted with respect to embedded BMC Modules in the immediately foregoing sentence, (iv) disassemble or reverse engineer any BMC Module, or decompile or otherwise attempt to derive any BMC Module source code from executable code, except to the extent expressly permitted by applicable law despite this limitation, (v) release any information to any third parties on the functionality or performance of the BMC Modules without BMC's prior written consent, or (vi) provide a third party with the results of any functional evaluation, or benchmarking or performance tests, without BMC's prior written approval. Additional usage restrictions may apply to certain third-party files or programs embedded in a BMC Module applicable installation instructions or release notes may contain the relevant details. Notwithstanding anything in this Agreement to the contrary, the licenses granted in this Agreement (A) do not grant You the right to use any BMC Module (such rights, if any, are granted under a separate license), (B) do not extend to any rights under any patents or patent applications under which BMC has any rights, and (C) do not extend to any use of the BMC Modules in combination with any product, service or software other than the Complementary Product for which it is registered and approved. FEES. You agree to pay any shipping or handling fees associated with the BMC Modules. You are responsible for taxes, if any. TERMINATION. This Agreement terminates automatically if You breach any of its terms. Either party may terminate this Agreement without cause on 30 days prior written notice. Upon termination, You must uninstall the BMC Modules, and either certify their destruction or return them to BMC. OWNERSHIP. BMC, or its affiliates or licensors, retains all right, title and interest in the BMC Modules and copies thereof, and any intellectual property, informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Modules to You. The BMC Modules are protected by applicable copyright, trade secret, patent and other intellectual and industrial property laws. As between You and BMC, You retain all right, title and interest in any intellectual property, information, industrial property and proprietary rights in the Complementary Products, excluding and subject to those contained in the BMC Modules. CONFIDENTIAL AND PROPRIETARY INFORMATION. The BMC Modules contain valuable confidential information and trade secrets of BMC. You may not use the BMC Modules other than as specifically allowed under the license granted in this Agreement. You may not disclose the BMC Modules or any part thereof, to third parties, except that (i) You may disclose the BMC Modules or parts thereof to Developer if Developer has obligations of confidentiality which are at least as protective of BMC s confidential information and trade secrets as the provisions of this Agreement and if Developer s use of the BMC Modules is consistent with the terms of this Agreement, and (ii) if You use a Complementary Product internally for production purposes, You may disclose the BMC Modules or parts thereof to its employees who are under obligations of confidentiality at least as protective of BMC s confidential information and trade secrets as the provisions of this Agreement, whose use of the BMC Modules is consistent with the terms of this Agreement, and who need to receive such disclosure in order to install, operate, support or maintain the Complementary BMC Modules. You agree to use all reasonable efforts to prevent the unauthorized use, copying, publication or dissemination of any BMC Module. WARRANTY DISCLAIMER. THE BMC MODULES ARE PROVIDED AS IS, WITH ALL FAULTS. BMC, ITS AFFILIATES AND LICENSORS SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND QUIET ENJOYMENT. BMC DOES NOT WARRANT THAT THE OPERATION OF THE BMC MODULES OR THE COMPLEMENTARY PRODUCTS WILL BE UNINTERRUPTED, VIRUS OR ERROR FREE, OR THAT THERE ARE NO DEFECTS. LIMITS ON BMC S LIABILITY. IN NO EVENT WILL BMC, ITS AFFILIATES OR LICENSORS, BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, THE BMC MODULES AND/OR ANY COMPLEMENTARY PRODUCT (INCLUDING WITHOUT LIMITATION LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OF USE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHER SUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. BMC S LIABILITY FOR DIRECT DAMAGES IS LIMITED TO THE GREATER OF (I) THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE BMC MODULE, IF ANY, AND (II) $1000. VERIFICATION. If requested by BMC, You will deliver to BMC written certification relating to Your use of the BMC Modules and/or the Complementary Products in compliance with the terms of this Agreement. BMC may audit Your use of the BMC Modules and/or Complementary Products to confirm such compliance. EXPORT CONTROLS. You will cooperate with BMC as reasonably necessary to ensure compliance with the laws and regulations of the United States and all other relevant countries, relating to exports and re-exports ( Export Laws ). You may not import, export, re-export or transfer, directly or indirectly, including via remote access, any part of the BMC Modules, or any other BMC information or technology, in violation of any such laws and regulations, or without any written governmental authorization required under applicable Export Laws. Neither the BMC Modules nor the underlying information or technology may be downloaded or otherwise provided or made available, either directly or indirectly, (i) into Cuba, Iran, Libya, Sudan or any other country subject to U.S. trade sanctions, to individuals or entities controlled by such countries, or to nationals or residents of such countries other than nationals who are lawfully admitted permanent residents of countries not subject to such sanctions; or (ii) to anyone on the U.S. Treasury Department s list of Specially Designated Nationals and blocked persons or the U.S. Commerce Department s Table of Denial Orders. BY OPENING THE PACKAGE, INSTALLING, PRESSING AGREE OR YES OR USING THE BMC MODULES, YOU AGREE TO THE FOREGOING AND REPRESENT AND WARRANT THAT YOU ARE NOT LOCATED IN, UNDER THE CONTOL OF, OR A NATIONAL OR RESIDENT OF ANY SUCH COUNTRY OR ON ANY SUCH LIST. DISPUTE RESOLUTION AND GOVERNING LAW. ANY CONTROVERSY OR CLAIM ARISING OUT OF THIS AGREEMENT, OR THE BREACH HEREOF, WILL BE SETTLED BY ARBITRATION ADMINISTERED BY THE AMERICAN ARBITRATION ASSOCIATION UNDER ITS COMMERCIAL ARBITRATION RULES IN HOUSTON, TEXAS IN ENGLISH. THE ARBITRATOR MUST FILE ALL FINDINGS WITHIN 30 DAYS AFTER THE FINAL ARBITRATION HEARING. JUDGMENT ON ANY AWARD RENDERED BY THE ARBITRATOR MAY BE ENTERED IN ANY COURT HAVING JURISDICTION THEREOF. NOTHING CONTAINED IN THIS SECTION WILL LIMIT BMC'S ABILITY TO SEEK EQUITABLE RELIEF IN ANY COURT. THE PARTIES WILL ARBITRATE DISPUTES IN CONFIDENCE. THIS AGREEMENT WILL BE GOVERNED BY THE SUBSTANTIVE LAWS OF THE STATE OF TEXAS. CHOICE OF LAW RULES OF ANY JURISDICTION AND THE UNITED NATIONS CONVENTION ON CONTRACTS FOR THE INTERNATIONAL SALE OF GOODS WILL NOT APPLY. U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section , DFARS ,DFARS , DFARS , and DFARS , as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX , USA. Any contract notices should be sent to this address.

204 MISCELLANEOUS TERMS. This Agreement constitutes the entire agreement between You and BMC relating to the matters covered hereby, and supersedes any prior or contemporaneous negotiations or agreements, whether oral or written, concerning the BMC Modules and any related subject matter. This Agreement may be modified only in a mutually signed, whether in writing or electronic, agreement between You and BMC. Neither Developer nor You may assign this Agreement or any rights granted by this Agreement to a successor, except in the event of merger, consolidation, or sale of all or substantially all of Your assets. Should any provision of this Agreement be invalid, or unenforceable, the remainder of the provisions will remain in effect. The parties have agreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la présente convention ainsi que les documents qui s y rattachent soient rédigés en anglais. BY OPENING THE PACKAGE, INSTALLING, PRESSING AGREE OR YES OR USING THE BMC MODULES, YOU ACKNOWLEDGE AND AGREE THAT YOUR AUTHORIZED REPRESENTATIVE HAS READ THIS AGREEMENT AND THAT YOU INTEND TO BE BOUND HEREBY, AS IF YOUR AUTHORIZED REPRESENTATIVE HAD SIGNED THIS AGREEMENT IN WRITING. THE INDIVIDUAL EXECUTING THIS AGREEMENT WARRANTS THAT HE OR SHE HAS THE AUTHORITY TO ACCEPT THE TERMS OF THIS AGREEMENT FOR YOU AND ON HIS OR HER OWN BEHALF. Third-Party Product Terms The following terms apply to third-party products that are included with or in a BMC Software product as described in the BMC Software, Inc., License Agreement that is applicable to the BMC Software product. OpenSSl License Copyright (C) 1995 Tim Hudson ([email protected]) All rights reserved. This package is documentation for the SSLeay implementation that was written by Eric Young ([email protected]). The documentation was written by Tim Hudson ([email protected]). This documentation can be distributed free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all the documentation found in this distribution. Copyright remains Tim Hudson's, and as such any Copyright notices in the documentation are not to be removed. If this documentation is used in a product, Tim Hudson should be given attribution as the author of this documentation. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code and documentation must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this documentation must display the following acknowledgement: This documentation was written by Tim Hudson ([email protected]) THIS DOCUMENTATION IS PROVIDED BY TIM HUDSON ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

205 Notes

206 *86784* *86784* *86784* *86784* *86784*