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 customer_support@bmc.com. (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