Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Supporting
BMC Impact Integration Web Services 8.6
July 2011
www.bmc.com
Copyright 2010 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. The information included in this documentation is the proprietary and confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights notices included in the product documentation.
Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see Before contacting BMC.
Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can
s s s s s s s s
read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation download products and maintenance report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
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
s s s
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
Send an e-mail message to customer_support@bmc.com. Use the Customer Support website at http://www.bmc.com/support.
Contents
Chapter 1 Introduction 15 15 15 16 16 16 16 17 18 18 19 21 21 23 25 Intended audience for web services development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internationalization considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Atrium service registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering BMC II Web Services with the BMC UDDI server . . . . . . . . . . . . . . . Overview of BMC Impact Integration Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . Platform and required tools or components for development . . . . . . . . . . . . . . . . BMC II Web Services overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II Web Services access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features of the BMC II Web Services server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of the BMC II Web Services server . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Securing web services
Securing BMC II Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Default keystore files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Modify the security configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Chapter 3 Guidelines for choosing client interfaces 31 31 31 32 32 33 35 35 43 44 44 44 45 46 48 58
Client components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for building a client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating the client proxy code (client stubs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary of BMC II Web Services operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II Web Services client sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing the BMC II Web Services operations . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4 BMC Impact Integration Web Services server Administration
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 mcell.dir file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Appendix A BMC Impact Integration Web Services Data Types 63
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Imported schema definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 baseClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 bufferType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 CellInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 ClassDefInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 ClassDefInfo_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 className . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 classNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 classOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 componentCauseId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 componentId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 componentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 componentStatusId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 connectionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 context_nio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Cstatus_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 cStatusHigh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 cStatusLow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 deleteBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 endDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 errorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 eventID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 filterName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 GetEventsResponse_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 GetQueryResultResponse_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 getSubclasses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 imFailure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 imName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 long_Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 messageClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 messageID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 messageType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 modeToSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 num_of_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 num_of_events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 num_of_results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
8 Book Title
onlyImpacted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 QueryMode_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 regID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 reliable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 resultCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 resultHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 retrieveResultHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 securityToken. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 serverName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 setOrCleared. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 SlotDefInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 SlotDefInfo_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 slotsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 SMComponent_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 SMComponentArray_element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 startDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 startIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 StateChangeType_element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 trueCause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 userName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Simple Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 IMMessageType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 IMBufferType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 DataType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 QueryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Complex Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Arrays from Built-In Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Value Choices, Name-Value Pairs, and Custom Complex Types . . . . . . . . . . . . . 92 Custom complex types in the WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Mapping: XSD data types to programming language data types . . . . . . . . . . . . . . . 102 Appendix B BMC Impact Integration Web Services API operations 103 104 104 104 105 107 108 109 110 112 113 115 117 118 120
9
PortType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AckEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EndQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetCellInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetFilterNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetQueryResultCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryClassDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
QueryComponentsByCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 QueryComponentsByStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 QueryData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 QueryEventByID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 QueryEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 QueryEventsByDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 QueryModelImpact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 QueryModelPossibleRootCauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 RegisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 RetrieveQueryResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 SendEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 SetMaintenanceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 SetManualStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 UnregisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Unsubscribe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Appendix C Glossary Index BMC Impact Manager Service 151 153 171
10
Book Title
Figures
BMC II Web Services server overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 48 49 51
Figures
11
12
Tables
BMC II Web Services server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details for the iiwsssl.jks keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details for the iiwscacerts.jks keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details for the iiwsssl.cer keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BMC II Web Services server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Complex Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CellInfo Child Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 26 26 26 33 39 49 50 52 55 57 59 64 85 89 96
Tables
13
14
Chapter
Introduction
This chapter introduces the BMC Impact Integration Web Services Developers Guide.
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
Support overview
You request the BMC Impact Integration Developers Kit through the BMC Developer Network website at http://devcon.bmc.com/. To obtain general support information, such as finding out how to extend the tools in the kit and develop integration applications, you can go to the BMC Developer Network. 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 Network Web site at: http://devcon.bmc.com/.
Chapter 1
Introduction
15
Deployment
If you have found a bug in the toolkit or an error in the documentation, please report it to BMC Customer Support. For information about how to contact support, see Customer support on page 3.
Deployment
The output of the BMC Impact Integration Web Services projects are sets of archive (.aar) files. The BMC II Web Services package is installed separately. For more information and installation instructions, see the BMC Impact Integration Web Services Web Services Getting Started Guide.
Security considerations
In this release, BMC II Web Services does not support WS-Security based authentication. It only supports the Transport-level security, the SSL security.
Internationalization considerations
Identify areas of your solution that must be able to support Level-1 internationalization. This level means your software should be able to deal with any non-ASCII characters from input and store them properly. If you are unsure of Level 1 internationalization requirement review them with an Internationalization architect.
16
The iiws_uddi_publish script publishes the BMC II Web Services web service onto the BMC UDDI registry server. The iiws_uddi_unpublish script un-publishes (deletes) the BMC II Web Services web service from the BMC UDDI registry server. The iiws_uddi_findsvr script looks up the BMC II Web Services service and provides a printout of the service information, if found.
right value.
2 Edit the bin/iiws_uddi_registry.properties file to set the values for the following
properties: uddiHostname: The hostname of the BMC UDDI registry server is running uddiPort: The Port number used by BMC UDDI Registry server uddiUsername: the user name for the BMC UDDI Registry server uddiPassword: The password for the BMC UDDI Registry server accessPointUrl: This is the endpoint for BMC II Web Services. You need to chose either the HTTP or the HTTPS URL.
3 After verifying the values in the iiws_uddi_env script and editing the values in
iiws_uddi_registry.properties file, you can run the following command scripts:
s
To publish the BMC II Web Services to the BMC UDDI registry, runiiws_uddi_publish. To unpublish the BMC II Web Services from the BMC UDDI registry, run
iiws_uddi_unpublish.
Chapter 1
Introduction
17
NOTE
The BMC II Web Services provides a pre-built web service. The web services developer is responsible for building the client.
Version 7.3.01 of the BMC II Web Services server was built and deployed with the TIBCO ActiveMatrix application. Previous to 7.3.01, it was built and deployed with the Systinet server platform. Those platforms are not supported for this release.
NOTE
The BMC II Web Services provides support for: Sending events from the event source to BMC Impact Manager. Retrieving data, events, and class definitions from BMC Impact Manager. Subscribing to events and receiving events from BMC Impact Manager.
Java 6 - it is important to install this prior to installing Tomcat JDK 6u16 or higher JRE 6u16 or higher
Eclipse 3.3.2 (Europa)- minimal version, Gannymede will work fine as well. Apache Tomcat 6.0.20 Axis2 1.5 The installation, quickstart, and user guides all have very good information to get you started
18
Axis2 1.5 WAR file You'll need to copy this to the tomcat "webapps" directory.
Chapter 1
Introduction
19
Figure 1
The BMC II Web Services server package includes the following components:
s
The BMC II Web Services archive (ImpactManager.aar) file that provides BMC II Web Services API for clients exchanges events and data with BMC Impact Manager cells through request and response. Web Services Description Language (WSDL), an XML document that defines the data types, messages, operations, and binding protocol of this web service. The Axis2 distribution.
20
A Tomcat web server that provides the HTTP environment and loads BMC II Web Services. UDDI help tools. Client samples.
You can view the BMC II Web Services server wsdl file through the following example URLs:
http://hostname:port/imws/services/ImpactManager?wsdl
Send events to BMC Impact Manager cell. Query data and events from BMC Impact Manager cell. Query class definitions from BMC Impact Manager cell. Polling events from BMC Impact Manager cell. Other administrator tasks.
For more information about these features, see Summary of BMC II Web Services operations on page 33.
Chapter 1
Introduction
21
Table 1 lists the names and descriptions for the BMC II Web Services API. Table 1
Operations Send events Connect Requests BMC II Web Services to connect with specific instances in the BMC Impact Manager network. Requests BMC II Web Services to disconnect from a connected instance. Sends an event to a connected BMC Impact Manager cell. Requests to end the query. Gets the total number of events or data objects that the BMC II Web Services server has retrieved in response to a query. Retrieves the class and slot definitions of a specific base class and its subclasses. Connects to a specific BMC Impact Manager cell and queries for data. Connects to a specific BMC Impact Manager cell and retrieves the component data attributes. Connects to a specific BMC Impact Manager cell and queries for components by a specific condition. Connects to a specific BMC Impact Manager cell and queries for components by a specific status. Connects to a specific BMC Impact Manager cell and retrieves events associated with a component object. Connects to a specific BMC Impact Manager cell and queries for the status of specific components. Connects to a specific BMC Impact Manager cell and queries for events. Connects to a specific BMC Impact Manager cell and queries for events that occurred within a specific date range. Connects to a specific BMC Impact Manager cell and queries for specific events by ID. Retrieves possible consumer components of a specified component. Retrieves a component or components that have either an immediate, direct relationship with the specified component, or that have status that were propagated to the component.
Disconnect SendEvent Query data, events, and service model EndQuery GetQueryResultCount
22
Table 1
Operations
mcell.dir
When the BMC II Web Services server is installed, 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 IIWSGatewayserver component. The following example shows the entries with the default port numbers.
cell cell local mc localhost:1828 IIWSGatewayserver mc 127.0.0.1:1859
Chapter 1
Introduction
23
In the standalone BMC II Web Services server installation, the mcell.dir file is installed under the $IIWS_HOME\Tomcat\webapps\imws\WEB-INF\etc or the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory.
IIWSGatewayserver
An essential component of the BMC II Web Services server is IIWSGatewayserver, which accepts connections and messages from BMC Impact Manager instances. It is enabled when the BMC II Web Services server starts. The IIWSGatewayserver 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 IIWSGatewayserver. The IIWSGatewayserver defaults to the local host system (IP address of 127.0.0.1) of the BMC II Web Services server and listens for events on port number 1859. For each BMC IM cell that sends events to the BMC II Web Services server, you specify the IIWSGatewayserver entry that identifies the server in the mcell.dir file of each sending cell.
24
Chapter
25
Table 2, Table 3, and Table 4 provide the details of those default keystore files. Table 2
Keystore FileName
Table 3
Keystore FileName
Type Password
Table 4
Keystore FileName
NOTE
BMC Software recommends that you replace the default trustore and certificate files with those that meet your requirements. For more information about replacing the keystore, see Modify the security configuration on page 26.
26
To set the HTTPS-only connector element 1 Open the server.xml file under the $IIWS_HOME/Tomcat/conf in a text editor. 2 In the server.xml file, locate the connector element by searching for the following
string:
Define a SSL HTTP/1.1 Connector
4 Save and Close the file. 5 Restart the BMC II Web Services Tomcat server.
Now the BMC II Web Services is accessible only through HTTPS
To change the keystore file 1 Open the server.xml file under the $IIWS_HOME/Tomcat/conf in a text editor. 2 In the server.xml file, locate the connector element by searching for the following
string:
27
3 Replace the iiwsssl.jks file with the keystore file that you want to use instead. 4 Save and Close the file. 5 Restart the BMC II Web Services Tomcat server.
Web service framework on which you built the client code Security certificate that the server and client uses
BMC II Web Services server provides a default keystore and a security certificate, both of which you can use with the HTTPS server. The following process demonstrates how to configure the client site to connect to the BMC II Web Services through HTTPS by using the BMC II Web Services default keystore files.
NOTE
These instructions are based on a client that is built on the Axis Java framework. If your client was built on another framework, refer to the documentation for your framework for information about building a secure client.
To configure a web service client to support HTTPS 1 Import the keystore certificate from the BMC II Web Services server. To import the
keystore certificate, you can do one of the following:
s
Use the web service tool to import the Java Key Store files from the BMC II Web servers server web services URL.
28
Copy the following directory and all its files from the server to the client system: $IIWS_HOME\Tomcat\webapps\imws\WEB-INF\security
2 Pass the trustStore and trustStorePassword environment variable values to the web
service client upon its startup. The trustStore environment variable stores the location of the Java Key Store file. The trustStorePassword environment variable is the password of the BMC II Web Services server keystore (the default password value is bmciiws). In the Axis Java framework, you can define these two environment variables in the client startup script as in the following example:
: "java -Djavax.net.ssl.trustStore=C:\IIWS_client\security\ iiwscacerts.jks - Djavax.net.sll.trustStorePassword=bmciiws"
3 Launch the client on the correct BMC II Web Services server endpoint according to
the HTTP server configuration. For example, for the HTTPS server, the client should communicate with the server through the following endpoint:
https://hostname:port/imws/services/ImpactManager
29
30
Chapter
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.
Client components
When you build a client interface, you use these components:
s s
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.
Chapter 3
31
32
Send events to BMC Impact Manager cell. Query data and events from BMC Impact Manager cell. Query class definitions from BMC Impact Manager cell. Subscribe to and get events from BMC Impact Manager cell. Other administrator tasks.
These operations are defined in the ImpactManager.wsdl. Table 5 provides you with the names and descriptions of the BMC II Web Services server operations. Table 5
Operations Send events Connect Requests BMC II Web Services to connect with specific instances in the BMC Impact Manager network. Requests BMC II Web Services to disconnect from a connected instance. Sends an event to a connected BMC Impact Manager cell. Requests to end the query. Gets the total number of events or data objects that the BMC II Web Services server has retrieved in response to a query. Retrieves the class and slot definitions of a specific base class and its subclasses. Connects to a specific BMC Impact Manager cell and queries for data. Connects to a specific BMC Impact Manager cell and retrieves the component data attributes. Connects to a specific BMC Impact Manager cell and queries for components by a specific condition. Connects to a specific BMC Impact Manager cell and queries for components by a specific status.
Disconnect SendEvent Query data, events, and service model EndQuery GetQueryResultCount
Chapter 3
33
Table 5
Operations
QueryComponentEvents
34
To enable a client to send events and data, call the following key operations in sequence:
1. Connect Before you send events, you must invoke the Connect operation. The Connect operation establishes a connection between BMC II Web Services server and the specified BMC Impact Manager instance. Execution of the Connect operation returns a connection ID. This connection ID is used in SendEvent and Disconnect operations. You can use this connection ID repeatedly until the Disconnect operation is called. Because you are connecting to a specific BMC Impact Manager instance, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file that is located on the BMC II Web Services server. 2. SendEvent
Chapter 3
35
Invoke the SendEvent operation to send an event to the BMC Impact Manager specified in the Connect operation. You must use the connection ID returned from the Connect operation for the destination cell. If your client is an event provider, you can connect and call the sendEvent operation repeatedly to send events to the same cell. The connection ID is valid until a Disconnect operation is called. 3. Disconnect The Disconnect operation terminates the connection between BMC II Web Services server and the specified BMC Impact Manager instance. After the Disconnect operation is called, the specified connect ID is no longer valid.
TIP
1. If your client application is an event provider, do not use the connect and disconnect operations frequently. Connect once, using the same connect ID to send events for an entire session, and disconnect at the end of the session. 2. Always use the connect and disconnect operations in pairs. Do not leave too many connect operations without a disconnect.
Client samples
BMC II Web Services provides the send events client sample code under the %IIWS_HOME%\Tomcat\webapps\imws\client_samples\testSendEvents directory.
Implementing queries
Using the available query features, you can enable a client to:
s s s
Retrieve events, data from a specific BMC IM instance Retrieve component information about service model component instances Query root cause and impact for a service model
After the client specifies the initial query request with the particular BMC Impact Manager instance, the BMC II Web Services server establish the connection with the BMC Impact Manager cell. The BMC II Web Services returns a response with a result handle which is used by the client with each query request in the query cycle. The returned response also contains the total number of objects available to this query. 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 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 an EndQuery request.
36
When querying, the client does not need to invoke a specific connection or disconnection request. With each query request, BMC II Web Services establishes a connection with a specific BMC Impact Manager instance. With the EndQuery, the BMC II Web Services disconnects from the BMC Impact Manager instance for this particular query request. The query operations have their own connection protocol. You do not have to call the Connect operation before calling a query. You establish a separate query connection when you call a query operation.
NOTE
For the service model queries, you must enter a component ID as an input parameter. You can obtain a component ID from the service model view in the BMC Impact Explorer or from the return values of other queries, such as QueryComponentsByCondition or QueryComponentsByStatus. Because you are connecting to specific a BMC Impact Manager instance, 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. 2. Get the total number of objects expected in the response to the query. The response from the initial query contains the result count, which is the total number of objects available for this query. Alternatively, you can call the getQueryResultCount operation to retrieve the result count from BMC II Web Services.
3. RetrieveQueryResult
The RetrieveQueryResult call specifies the number of events or data objects that the client wants to receive. The maximum number of objects each RetrieveQueryResult can get is defined by the MaxReturnEventListSize configuration parameter. The default value is 20. You can modify this value by changing the MaxReturnEventListSize parameter in the ImWebServices.conf file. See the BMC ProactiveNet Performance Management Web Services Getting Started Guide for more information.
Chapter 3
37
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 RetrieveQueryResult 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 RetrieveQueryResult 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.
4. EndQuery
The EndQuery call tells the BMC II Web Services server to end the query cycle.
TIP
The client must call the EndQuery operation to perform the following tasks:
s s s
Clean up the query context in the BMC II Web Services server Clean up the memory cache Close the connection with the BMC Impact Manager instance
Client samples
BMC II Web Services provides the query client sample code under the %IIWS_HOME%\Tomcat\webapps\imws\client_samples\testDataQueries directory. This sample program contains query examples for all the BMC II Web Services query operations. It demonstrates how to invoke the query request and how to retrieve the results.
Client samples
You can find the query class definition sample in the %IIWS_HOME%\Tomcat\webapps\imws\client_samples\testDataQueries directory.
38
The iiwsClientQueryClassDefinitions() method shows how to invoke the query class definitions call. The printClassInfo() method demonstrates the details of how to retrieve the slot information and recursively walk through the children classes.
Subscription requests
To receive events, your client interface must invoke subscription requests through the Subscribe () operation. Client then enter the polling loop the get events periodically from IIWS.
Selector
Selectors define the criteria that determine which events your client receives. You specify a selector type in your subscription request.
Selector choices
BMC II Web Services provides a default select file, the iiws.selector, which is located under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory. The iiws.selector provides the following basic selectors:
s s s
Chapter 3
39
You can add more selectors to the selector file or use your own selector file. For more information on the selector file and selector processing, see the BMC ProactiveNet Performance Management Web Services Getting Started Guide.
To build a client interface that receives events propagated from a BMC Impact Manager cell, invoke the following key operations in sequence:
1. Subscribe
If you need to receive events from a BMC Impact Manger, you can send the Subscribe request to BMC II Web Services. The subscribe request has the parameters of context and filterName and the flag that indicates whether this is a reliable or an unreliable subscription. The context is a string that represents this subscribe request. The filterName is the name of a selector in the selector file, (for example, iiws.selector). The selector defines the criteria that determine which events this subscriber receives. The client context and filterName uniquely identify this particular subscription request. All the subsequent calls for the same subscription, (for example, GetEvents, AckEvents, and Unsubscribe) have to provide the same client context and filterName input parameters. When the BMC II Web Services gateway server receives the events propagated from a cell, it maps the events against all the selectors for current subscriptions. If matches are found, the event is saved for each subscriber until the client retrieves it.
40
NOTE
The callbackURL input parameter is not used in the Subscribe API in BMC II Web Services 7.4.
2. GetEvents
After Subscribe succeeds, the client can call GetEvents periodically to retrieve events from BMC II Web Services. The GetEvent operation passes the same context and filterName that were in the Subscribe call. The third input parameter is num_of_events, which tells the BMC II Web Services gateway server the number of events that the client wants to retrieve during this operation. The BMC II Web Services gateway server uses the context and filterName to locate the subscription. If found, and if there are events existing for this subscriber, events are returned to the client. The num_of_events returned in the response is the actual number of events this operation returned. It is always equal to or less than the value of the input num_of_events from the GetEvent request.
3. AckEvents
Following the GetEvents request, if the number of events returned (num_of_events) is lager than zero, the client must call the ActEvents operation. Upon receipt of the ActEvents request, the BMC II Web Services gateway server cleans up the events from the server side. The number of events in the AckEvent operation must equal the number of events returned from the getEvent call. For example, from a client Call the GetEvents request with a num_of_events input of 30. There are 25 events returned, and the num_of_events in the returned
GetEventsResponse is 25.
The client must call AckEvents with a num_of_events input of 25. 4.Unsubscrbe The Unsubscribe operation terminates the subscription. After receiving this request, the BMC II Web Services gateway server cleans up all the saved events for this subscription and deletes subscription information from the server side.
Client samples
BMC II Web Services provides the subscribing and receiving events sample program under %IIWS_HOME%\Tomcat\webapps\imws\client_samples\testReceiveEvents.
Chapter 3
41
UTF-8 encoding
The Impact Manager cell required the all input string is UTF-8 encoded. BMC II Web Services does not translate string code. The BMC II Web Services client must specifically encode all the input strings to UTF-8 before sending them to BMC II Web Services.
42
Chapter
This chapter describes configuration files that affect how the underlying BMC II Web Services 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 chapter 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 44 44 45 46 48 58 58 58 61 62
Chapter 4
43
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 $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory, in the ImWebServices.conf 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.
44
When programming the web service client, you specify the selector name to invoke in the subscription request (Subscribe). 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 ImWebServices.conf 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.
Chapter 4
45
Characteristics
Characteristics
Message selector set files have the following characteristics:
s
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 Web Services 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 Web Services 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.
46
Characteristics
Each line in a message selector contains only one message selector criterion. The message selector file supports the following comparison operators
s s s s
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.
s
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.
Chapter 4
47
Format
Format
Figure 2 depicts the structure of the message selector set file. Figure 2 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
s
message selector set headers, described in Message selector set header on page 48 message selector headers, described in Message selector header on page 49
Message selector criteria are described in Message selector criteria on page 51.
48
Format
Table 7
Parameter
SelectorSetName=
FormatVersion=
minimum version of the BMC II Web Services Server required to run the message selector using this file
Optional
Version=
version number of the message selector Optional set file, specified manually by the developer or integration end-user date when the file last changed, Optional 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:
s s
ChangeDate=
Description= Enable=
Optional Required
Figure 3
SelectorSetName=testselector FormatVersion=2 Version=7.1 ChangeDate=November 14, 2007 Description=This file contains the event selector tests Enable=TRUE
s s
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
Chapter 4
49
Format
A message selector header must precede each collection of message selector criteria in the message selector set. Table 8 describes the required and optional message selector header parameters that precede each message selector. Table 8
Parameter SelectorName=
Description= FailOnMissingSlot=
free-text description of the message selector indicates whether the match for the message selector fails if a slot specified in the message selector criteria is missing from the message Valid values:
s
Optional Optional
TRUE the match for the message selector fails if a slot specified in the message selector is missing from the message FALSE missing slots cause the line to be ignored
If the message that is being examined does not include any of the slots that are being tested by the message selector, the comparison will never result in a match. This is true even when the parameter statement is FailOnMissingSlot=false. If you use the reqdslot keyword in the message selector criteria, it is in effect only when FailOnMissingSlot is set equal to false. IsSubSelector 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:
s s
Optional
Enable=
Required
50
Format
Figure 4
SelectorName=EVENT_SELECTOR Description=Selectors for all events of class EVENT FailOnMissingSlot=false IsSubSelector=true Enable=TRUE
Format issues
Messages selector functions, which are internal to the message selector file, are described in Table 9 on page 52. Operators are described in Table 10 on page 55.
s
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.
Chapter 4
51
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 9
Function
$HostName
$ClassName
class name of the source message. This function can also be inserted in the new message as a slot value to set the class value of a destination event. Examples: slot.imclass=$ClassName $ClassName="EVENT"
slot.slotname
compares the value of slot.slotname in the message with the value specified to the right of the operator. When the slot and the value are both present in the message, the criterion is considered a match. Example: slot.severity = Critical
52
Format
Table 9
Function
$doselector
$slotPresent
specifies a slot name that must appear in the message that is being examined for the criterion to be a match Example: $SlotPresent(slot.severity) Unlike the slot.slotname criterion also described in this table, the value of the slot is not considered.
Chapter 4
53
Format
Table 9
Function
$slotMissing
$TimeT
returns the number of seconds since January 1, 1970 in number format. Examples: mc_date=$TimeT Slot.mc_date=$TimeT
$Format
similar to printf, uses %s to insert values into a string, expands \t and \n. Note: %s is the only formatter available for $format. Examples: mc_origin=$format("%s:%s", slot.p_agent, slot.p_agent_port) $format("%s:%s", slot.p_agent, slot.p_agent_port)=mc_origin.
$LocalTime
enables you to specify the local time using the same format parameters as strftime Examples: time=LocalTime("%I:%M:S%p") Slot.time=LocalTime("%I:%M:S%p")
$GmtTime
enables you to specify GMT time using the same format as strftime Examples: time=$GmtTime("%I:%M:S%p) Slot.time=$GmtTime("%I:%M:S%p")
$subString
extracts specified components of a string Example: msg=$subString(slot.test, 0, 20) where the first parameter (slot.test in the example) is the slot or string to divide; the second parameter (0 in example) is the index of the first character to include; and the third parameter (20 in example) is the number of characters to include.
$ToLower
$ToUpper
54
Format
Table 9
Function
$GetListValue
$IpFromName
performs a domain name server (DNS) lookup for the host name associated with the specified IP address Example: IP=$IpFromName("hostname.domain")
$HostFromIp
performs a DNS lookup for the IP address associated with the specified host name Example: mc_host=$HostFromIp(slot.srcIP)
Table 10 describes the operators used for comparison in a message selector set file. Table 10
Operators =
!=
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.
!=~
regular expression operator If the regular expression fails to match, then the entire line succeeds. If the regular expression matches the value, then the line fails. Example: slot.severity!=~"MAJ~."
Chapter 4
55
Format
Table 10
Operators || OR
&& AND
symbol and literal string, both of which specify an AND relationship between successive lines of message selector criteria or between successive message selector groups Example: AND relationship between message selector groups { slot.Test=EVENTS slot.mc_host=EVENTS } AND { slot.Test=EVENTS2 slot.mc_host=EVENTS2 } By default, AND relationships exist between successive lines of message selector criteria.
{}
indicates groups of alternate message selector criteria within an individual message selector. A group can be nested one level deep. Example: { { slot.Test=EVENTS slot.mc_host=EVENTS } AND { slot.Test=EVENTS2 slot.mc_host=EVENTS2 } }
56
Format
Table 10
Operators >
>=
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 11 on page 57 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. Table 11
Keyword metaslot.
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"
reqdslot.
designates a slot as a required slot. If the FailOnMissingSlot parameter is set equal to FALSE and if the message does not contain the specified required slot, it will not pass the message selector criteria. If the FailOnMissingSlot parameter is set equal to TRUE, then the BMC II C APIs ignore the reqdslot indicator. Example: reqdslot.msg="TEST"
slot.
designates a readable slot value in regular expressions slot.msg=~"event from slot.host" The BMC II C APIs return the value of host before forwarding the regular expression to the expression library.
NOTE
For additional information about selector files, see the BMC Impact Integration Developers Kit C API Developer Guide.
Chapter 4
57
2 In a text editor, open the iiws.selector. 3 Modify the different file componentsselector set header, selector header, selector
content, and operatorsas 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 ImWebServices.conf file accordingly.
5 Ensure that the selector file can be read by the user under whose permissions the
web services server is running.
6 If the BMC II Web Services server is running, restart it to initialize the changes.
Configuration file
The BMC II Web Services configuration file, ImWebServices.conf, is a text file. The configuration file is stored in the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory that resides on the BMC II Web Services server. It is accessed at runtime by the BMC II Web Services server. The ImWebServices.conf file is preconfigured so that you do not have to modify the ImWebServices.conf file to run the BMC II Web Services server. Later, as you learn more about your integration needs, you can modify the parameters in the ImWebServices.conf file.
58
Table 12
Group Message Buffer
The value of this parameter cannot be less than 60 seconds. When a connection is established, the BMC II Web Services server sends buffered messages that are designated for the BMC Impact Manager cell with which a connection is established.
MessageBufferResendCount
MessageBufferExpandPercentag The percentage that the message buffer can expand. e Default: 10
Chapter 4
59
Table 12
Group
Event Persistency
60
Table 12
Group Impact Manager Web services
2 Optional. Modify the file to include any optional BMC II Web Services server
parameters that you want to use. Table 12 on page 59 lists these parameters.
3 Save the file using the file name of your choice and the file extension .conf. 4 Ensure that the user can read the configuration file under the permissions that the
BMC II Web Services server is running.
mcell.dir file
mcell.dir file
The mcell.dir file lists the identifying information for all BMC Impact Manager product instances (cells) and the event receivers (IIWSGatewayserver) 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.
62
Appendix
This Appendix describes both the namespace definitions and the data types of the ImpactManager.wsdl.
Data types
The BMC II Web Services data types consist of element declarations, simple data type definitions, and complex data type definitions. These data definitions and element declarations are defined within the <wsdl:types> section of the ImpactManager.wsdl itself and in four imported schema definition documents.
NOTE
The BMC Impact Integration Web Services use a document-style invocation, which passes literal XML documents in its message parts. The document-style invocation requires the element attribute. Consequently, the <wsdl:types> section consists mainly of element declarations.
Appendix A
63
Elements
Elements
Table 13 describes the elements that the <wsdl:types> section exposes. These elements are derived from built-in, simple, and complex data types. Table 13
Element baseClass bufferType CellInfo_Array ClassDefInfo_Array ClassDefInfo_element className classNames classOnly comment componentCauseId componentId componentStatus componentStatusId condition connection connectionId context context_nio deleteBuffer endDate errorCode eventID filterName GetEventsResponse_ element
Elements (part 1 of 2)
Built-in Data Type string string string boolean string string string string string string long long string string boolean string int string string Simple Type IMBufferType Complex Type ArrayOf_CellInfo ArrayOf_ClassDefInfo ClassDefInfo GetEventsResponse GetQueryResultResponse Event
GetQueryResultResponse _element getSubclasses imFailure imname long_Response message messageClass boolean string string long string
64
Elements
Table 13
Element messageID
Elements (part 2 of 2)
Built-in Data Type string string int int int boolean string string string string boolean int string string string string boolean string string long int boolean string Simple Type IMMessageType Complex Type QueryMode ArrayOf_SlotDefInfo SlotDefInfo SMComponent ArrayOf_SMComponent StateChangeType
messageType modeToSet num_of_components num_of_events num_of_results onlyImpacted password query QueryMode_element query_ev regID reliable resultCode resultHandle retrieveResultHandle securityToken serverName setOrCleared SlotDefInfo_Array SlotDefInfo_element slotsList SMComponent_element SMComponentArray_ element startDate startIndex StateChangeType_ element timeout trueCause userName
Appendix A
65
baseClass
baseClass
The declaration for the element baseClass is shown below. This element is used as an input parameter in the query operations QueryComponentsByStatus and QueryClassDefinitions. The baseClass value specifies the class at which the query starts.
<xsd:element name=baseClass nillable=true type=xsd:string/>
bufferType
The element declaration for the element bufferType is shown below.
<xsd:element name=bufferType nillable=true type=tns:IMBufferType/>
The bufferType element specifies one of the enumerated buffering routines defined under the simple type definition of IMBufferType in this namespace. The simple type from which the element is defined uses the built-in type string. The bufferType element is valid even when it carries no content. The buffertype element is part of the Connect_Request message. See the description of the simple type IMBufferType under IMBufferType on page 87 for more information about the underlying simple type.
CellInfo_Array
The <wsdl:types> section describes the CellInfo_Array element. Its element declaration is shown below.
<xsd:element name=CellInfo_Array type=tns:ArrayOf_CellInfo/>
The CellInfo_Array element is defined from the complex type ArrayOf_CellInfo. See the description of the ArrayOf_CellInfo complex type under ArrayOf_CellInfo on page 97 for more information about the underlying complex type.
66
ClassDefInfo_Array
ClassDefInfo_Array
The element declaration for the element ClassDefInfo_Array is shown below.
<xsd:element name=ClassDefInfo_Array type=tns:ArrayOf_ClassDefInfo/>
This element references the complex type ArrayOf_ClassDefInfo, described on page 98.
ClassDefInfo_element
The element declaration for the element ClassDefInfo_element is shown below.
<xsd:element name=ClassDefInfo_element type=tns:ClassDefInfo/>
This element references the complex type ClassDefInfo, described on page 97.
className
The element declaration for className is shown below.
<xsd:element name=className nillable=true type=xsd:string/>
Used in the QueryClassDefinitions operation, the className parameter specifies the name of a particular class definition for the query to retrieve.
classNames
The element declaration for the element classNames is shown below.
<xsd:element name=classNames nillable=true type=xsd:string/>
Appendix A
67
classOnly
The classNames value is defined by the built-in type string. It is valid even when it carries no content. The classNames element refers to a specific message class. Used in query operations, the classNames element specifies a class of related events for which the web service client is inquiring. Multiple class names can be passed in a single string value, with a pipe symbol (|) separating the class names. The element classNames is part of the QueryEventsByDate_Request message. It is implemented with the startDate and endDate elements. See also startDate on page 83 and endDate on page 72.
classOnly
The declaration for the Boolean element classOnly is shown below.
<xsd:element name=classOnly type=xsd:boolean/>
Used in the QueryClassDefinitions operation, the classOnly element, if set to true, restricts the query to return class definitions only, not slots or slot definitions.
comment
The declaration for the element comment is shown below.
<xsd:element name=comment nillable=true type=xsd:string/>
The comment element is used as input parameter in the SetMaintenanceMode and SetManualStatus operations. You can include explanatory text about the reason for setting the maintenance mode or the manual status of the component.
componentCauseId
The declaration for the element componentCauseId is shown below.
<xsd:element name=componentCauseId nillable=true type=xsd:string/>
68
componentId
componentId
The declaration for the element componentId is shown below.
<xsd:element name=componentId nillable=true type=xsd:string/>
The componentId parameter is used in several queries and operations. It specifies the universal data ID (mc_udid) of the component object to be retrieved.
componentStatus
The declaration for the element componentStatus is shown below.
<xsd:element name=componentStatus nillable=true type=xsd:string/>
The element componentStatus is used as a parameter for queries and operations. It specifies one of the computed statuses of a component: status, self_status, computed_status, impact_status, and manual_status.
componentStatusId
The declaration for the element componentStatusId is shown below.
<xsd:element name=componentStatusId nillable=true type=xsd:string/>
condition
The element declaration for the element condition is shown below.
<xsd:element name=condition nillable=true type=xsd:string/>
Used as an input parameter in the QueryComponentsByCondition operation, the condition element specifies the selection criteria for a component. It specifies the selection criteria in a where clause that follows Master Rule Language syntax and conventions.
Appendix A
69
connection
connection
The <wsdl:types> section contains the element declaration for the element connection.
<xsd:element name=connection type=xsd:long/>
The connection value is the long integer assigned to a specific BMC Impact Manager instance connection request. (See also the connectionId element.) It is defined by the built-in type long. The connection element is part of the following messages:
s s
Disconnect_Request SendEvent_Request
connectionId
The <wsdl:types> section contains the element declaration for the element connectionId.
<xsd:element name=connectionId type=xsd:long/>
The connectionId value is the long integer (with a minimum value of 9223372036854775808 and maximum of 9223372036854775807) assigned to a specific BMC Impact Manager instance connection request. It is defined by the builtin type long. The connectionId element is part of the following messages:
s s
Connect_Request Connect_Response
context
The <wsdl:types> section contains the element declaration for the element context.
<xsd:element name=context nillable=true type=xsd:string/>
70
context_nio
The context value is a literal or string representation (called the context ID) that identifies the web service client. It is defined by the built-in type string. It is valid even when it carries no content. The context element is part of the following messages:
s s
Subscribe_Request Unsubscribe_Request
context_nio
The declaration for the element context_nio is shown below.
<xsd:element name=context_ack nillable=true type=xsd:string/>
The context_nio element is used to specify web service clients in GetEvents and AckEvents operations.
Cstatus_element
The declaration for the element Cstatus_element is shown below.
<xsd:element name=Cstatus_elementtype=tns:CStatus/>
The Cstatus_element references the complex type CStatus, which is described on page 100.
cStatusHigh
The declaration for the element cStatusHigh is shown below.
<xsd:element name=cStatusHigh nillable=true type=xsd:string/>
Used as a parameter in the QueryComponentsByStatus operation, it designates the highest component status value taken from the status values of self_status, computed_status, impact_status, and manual_status. The CStatusHigh and CStatusLow parameter values define a range of values.
Appendix A
71
cStatusLow
cStatusLow
The declaration for the element cStatusLow is shown below.
<xsd:element name=cStatusLow nillable=true type=xsd:string/>
Also used as a parameter in the QueryComponentsByStatus operation, it designates the lowest component status value taken from the status values of self_status, computed_status, impact_status, and manual_status.
deleteBuffer
The <wsdl:types> section contains the element declaration for the element deleteBuffer.
<xsd:element name=deleteBuffer type=xsd:boolean/>
The deleteBuffer value is a boolean indicator that tells whether to delete the persistent buffer (where the events and data are stored) when the web service disconnects from the BMC Impact Manager instance. It is defined by the built-in type boolean. The deleteBuffer element is part of the Disconnect_Request message.
endDate
The <wsdl:types> section contains the element declaration for the element endDate. Its element declaration is shown below.
<xsd:element name=endDate nillable=true type=xsd:dateTime/>
The endDate value is defined by the built-in type dateTime. It is valid even when it carries no content. Used in query requests by the web service client, the endDate defines a specific date and time, typically in GMT. The web service client uses the endDate, along with the startDate, to make a query for events within a specified time frame. The endDate is part of the QueryEventsByDate_Request message.
72
errorCode
errorCode
The declaration for the element errorCode is shown below.
<xsd:element name=errorCode nillable=true type=xsd:int/>
The errorCode element contains an integer that represents a BMC Impact Integration Web Services server error message. The SetManualStatus and SetMaintenanceMode operations return error codes in their responses.
eventID
declaration for the element eventID is shown below.
<xsd:element name=eventID nillable=true type=xsd:string/>
The event ID specifies the unique event identifier (mc_ueid) associated with the event that the client is requesting.
filterName
The <wsdl:types> section contains the element declaration for the element filterName.
<xsd:element name=filterName nillable=true type=xsd:string/>
The filterName value defines the name of the event filter (also called the selector) to which the web service client subscribes. Events that match the criteria of the specified selector are dispatched to the web service client. This element is defined by the builtin type string. It is valid even when it carries no content. The filterName element is part of the following messages:
s s
Subscribe_Request Unsubscribe_Request
Appendix A
73
GetEventsResponse_element
GetEventsResponse_element
The declaration for the element GetEventsResponse_element is shown below.
<xsd:element name=GetEventsResponse_element nillable=true type=tns:GetEventsResponse/>
The GetEventsResponse_element references the complex type GetEventsResponse, described on page 100.
GetQueryResultResponse_element
The declaration for the element GetQueryResultResponse_element is shown below.
<xsd:element name=GetQueryResultResponse_element nillable=true type=tns:GetQueryResultResponse/>
The GetQueryResultResponse element references the complex type GetQueryResultResponse, described on page 100.
getSubclasses
The declaration for the Boolean element getSubclasses is shown below.
<xsd:element name=getSubclassestype=xsd:boolean/>
Used as Boolean indicator in the QueryComponentsByStatus operation, it indicates whether to extend the query to the subclasses of the designated base class.
imFailure
The declaration for the element imFailure is shown below.
<xsd:element name=imFailure nillable=true type=xsd:string/>
The element imFailure is used in fault messages as the parameter that contains the fault error.
74
imName
imName
The <wsdl:types> section contains the element declaration for the element imName.
<xsd:element name=imName nillable=true type=xsd:string/>
The imname element specifies the name of the BMC Impact Manager instance. It is defined by the built-in type string. It is valid even when it carries no content. The imname element is part of the Connect_Request message.
long_Response
The <wsdl:types> section contains the element declaration for the element long_Response.
<xsd:element name=long_Response type=xsd:long/>
The long_Response value is the long integer that represents the response element received from the web services component. It is defined by the built-in type long. The long_Response element is part of the Connect_Response message.
message
The <wsdl:types> section contains the element declaration for the element message. Its element declaration is shown below.
<xsd:element name=message nillable=true type=event:Event/>
The message element contains the event information exchanged between BMC Impact Integration Web Services and the BMC Impact Manager instance. Its data type is a complex type called Event, defined in the schema definition file Event.xsd. This element of type Event is valid even when it carries no content. The message element is part of the SendEvent_Request message. See the description of the Event complex type under Event on page 95 for more information about the underlying complex type.
Appendix A
75
messageClass
messageClass
The <wsdl:types> section contains the element declaration for the element messageClass.
<xsd:element name=messageClass type=xsd:string/>
The messageClass value specifies the name of the class of the event or data. The value can be any valid class name. It is defined by the built-in type string. The messageClass element is part of the SendEvent_Request message.
messageID
The <wsdl:types> section contains the element declaration for the element messaageID. Its element declaration is shown below.
<xsd:element name=messageID nillable=true type=xsd:string/>
The messageID value is defined by the built-in type string. It is valid even when it carries no content. Used in query operations, the messageID represents the event ID or data ID of the information for which the web service client is inquiring. The messageID is part of the QueryEventByID_Request messages.
messageType
The <wsdl:types> section contains the element declaration for the element messageType.
<xsd:element name=messageType nillable=true type=tns:IMMessageType/>
The messageType element specifies one of the enumerated message types defined under the simple type definition of IMMessageType in this namespace. The simple type from which the element is defined uses the built-in type string. The messageType element is valid even when it carries no content. Used to send event or data information, the messagetype element is part of the SendEvent_Request message. See the description of the simple type IMMessageType under IMMessageType on page 86 for more information about the underlying simple type.
76 BMC ProactiveNet Performance Management Web Services Developer Guide
modeToSet
modeToSet
The declaration for the element modeToSet is shown below.
<xsd:element name=modeToSet nillable=true type=xsd:string/>
Used as an input parameter in the SetMaintenanceMode operation, it defines the maintenance mode that the operation will set.
num_of_components
The declaration for the element num_of_components is shown below.
<xsd:element name=num_of_components type=xsd:int/>
The num_of_components element is an integer that indicates the number of components that a query returns.
num_of_events
The <wsdl:types> section contains the element declaration for the element num_of_events.
<xsd:element name=num_of_events type=xsd:int/>
Used in query and polling operations, the num_of_events element represents both an input and an output argument. It is part of the GetEvents_Request and Response messages. Its value is an integer that defines the number of events that the web service client has requested and the number of events that the server is able to return per polling call or query. The value of the request (the input argument) and the value of the response (the output argument) can be different. When used in query operations, the num_of_events element is implemented with the startIndex element. See startIndex on page 84 for more information.
Appendix A
77
num_of_results
num_of_results
The declaration for the element num_of_results is shown below.
<xsd:element name=num_of_results type=xsd:int/>
Used as an input parameter in the RetrieveQueryResults operation, it specifies the number of query results that are requested.
onlyImpacted
The declaration for the element onlyImpacted is shown below.
<xsd:element name=onlyImpacted type=xsd:boolean/>
The Boolean element onlyImpacted indicates whether the query is restricted to those events that affect the mode of the component (impact events), and not direct events that
originate from the component. The onlyImpacted parameter is used in the QueryComponentEvent operation.
password
The <wsdl:types> section contains the element declaration for the element password.
<xsd:element name=password nillable=true type=xsd:string/>
The password element specifies the password that is defined for a BMC Impact Manager instance. It is defined by the built-in type string. It is valid even when it carries no content. The password element is part of the Connect_Request message.
query
The <wsdl:types> section contains the element declaration for the element query. Its element declaration follows.
78
QueryMode_element
The query value is defined by the built-in type string. It is valid even when it carries no content. The web service client uses the query element to connect with specific BMC Impact Manager instances and initiate query requests for events or data.
NOTE
The query contents have to be a valid Impact Manager cell communication commands for data and event manipulation. The syntax for the communication command is not within the scope of this documentation. Client developer needs to be familiar with cell communication commands to construct the query. The query element is part of the QueryEvents_Request and the QueryData_Request messages.
QueryMode_element
The declaration for the element QueryMode_element is shown below.
<xsd:element name=QueryMode_element type=tns:QueryMode/>
The QueryMode_element references the simple type QueryMode, described on page 88.
regID
The declaration for the element regID is shown below.
<xsd:element name=regID nillable=true type=xsd:string/>
The regID element is the registration ID assigned to registration requests that are part of the RegisterStateChange and UnregisterStateChange operations. The registration ID is used to associate your integration component with the data instance that the RegisterStateChange operation creates in the BMC SIM cell.
Appendix A
79
reliable
reliable
The declaration for the element reliable is shown below.
<xsd:element name=reliable type=xsd:boolean/>
The Boolean indicator reliable is used in subscription requests to guarantee delivery of messages and to persist messages when the connections among the web service client, BMC II Web Services server, and the C APIs are disrupted.
resultCode
The declaration for the element resultCode is shown below.
<xsd:element name=resultCode type=xsd:int/>
The resultCode element contains an integer that specifies the server response to the unregister state change request.
resultHandle
The <wsdl:types> section contains the element declaration for the element resultHandle. Its element declaration is shown below.
<xsd:element name=resultHandle nillable=true type=xsd:string/>
The resultHandle value is defined by the built-in type string. It is valid even when it carries no content. The resultHandle element refers to an ID that the web service client attaches to its query requests. This ID is taken from the resultHandle value that the server sends to the client in its initial query response. The client uses the resultHandle element to identify a series of query requests in a query cycle. It is part of the following query request messages:
s s
GetQueryResultCount_Request EndQuery_Request
80
retrieveResultHandle
EXAMPLE
The web service client initiates a _queryEvents_Request. The BMC II Web Services server responds with a resultHandle of 100. The _getQueryResultCount, and _endQuery request messages that the client launches in the same query cycle carry the same resultHandle value of 100.
retrieveResultHandle
The declaration for the element retrieveResultHandle is shown below.
<xsd:element name=retrieveResultHandle nillable=true type=xsd:string/>
Used in query requests, the retrieveResultHandle element contains a string type that contains the ID returned by the servers response to the initial query request. This ID is attached to all query requests in the query cycle.
securityToken
The declaration for the element securityToken is shown below.
<xsd:element name=securityToken nillable=true type=xsd:string/>
serverName
The declaration for the element serverName is shown below.
<xsd:element name=serverName nillable=true type=xsd:string/>
The serverName element is a string type that specifies the name of the BMC II Web Services server that will be receiving the state change events through the RegisterStateChange operation.
Appendix A
81
setOrCleared
setOrCleared
The declaration for the element setOrCleared is shown below.
<xsd:element name=setOrCleared type=xsd:boolean/>
Used in the bmiiws_setMaintenanceMode operation, the setorCleared Boolean indicator specifies whether the selected component is available to have its maintenance mode set.
SlotDefInfo_Array
The declaration for the element SlotDefInfo_Array is shown below.
<xsd:element name=SlotDefInfo_Array type=tns:ArrayOf_SlotDefInfo/>
The element SlotDefInfo_Array references the complex type, ArrayOf_SlotDefInfo, defined on page 100.
SlotDefInfo_element
The declaration for the element SlotDefInfo_element is shown below.
<xsd:element name=SlotDefInfo_elementtype=tns:SlotDefInfo/>
The SlotDefInfo_element references the complex type SlotDefInfo, described on page 99.
slotsList
The declaration for the element slotsList is shown below.
<xsd:element name=slotsList nillable=true type=xsd:string/>
82
SMComponent_element
The slotsList is an output parameter for several queries. It is a string description that specifies the slot name or names, the values for which the query returns. The slot names in the string are separated by commas, as in ','. See also the complex type SlotDefInfo on page 99 for more information.
SMComponent_element
The declaration for the element SMComponent_element is shown below.
<xsd:element name=SMComponent_element type=tns:SMComponent/>
The SMComponent_element references the complex type SMComponent, described on page 98.
SMComponentArray_element
The declaration for the element SMComponentArray_element is shown below.
<xsd:element name=SMComponentArray_element type=tns:ArrayOf_SMComponent/>
The SMComponentArray_element references the complex type ArrayOf_SMComponent, described on page 98.
startDate
The <wsdl:types> section contains the element declaration for the element startDate. Its element declaration is shown below.
<xsd:element name=startDate nillable=true type=xsd:dateTime/>
The startDate value is defined by the built-in type dateTime. It is valid even when it carries no content. Used in query requests by the web service client, the startDate defines a specific date and time, typically in GMT. The web service client uses the startDate, along with the endDate, to make a query for events within a specified time frame. The startDate is part of the QueryEventsByDate_Request message.
Appendix A
83
startIndex
startIndex
The <wsdl:types> section contains the element declaration for the element startIndex.
<xsd:element name=startIndex type=xsd:long/>
Used in query operations, the startIndex value is the long integer that indicates the position in the event or data object list from which the client can request a specific number of events or data objects from the BMC II Web Services server. The startIndex is implemented with the num_of_events element.
EXAMPLE
A query has generated 100 events for the specified result handle ID. The web service client invokes a call to get the query results. The call specifies a startIndex of 50 and requests that 20 events (num_of_events value) be sent. The BMC II Web Services server returns events 50 through 69.
StateChangeType_element
The declaration for the element StateChangeType_element is shown below.
<xsd:element name=StateChangeType_element type=tns:StateChangeType/>
The StateChangeType_element references the complex type StateChangeType, described on page 101.
timeout
The <wsdl:types> section contains the element declaration for the element timeout.
<xsd:element name=timeout type=xsd:int/>
The timeout value is the time that the SendEvent operation, which carries the event message, waits for a response from the BMC Impact Manager instance. If no response is received within the specified time, then the events and data are stored in the bufferif one is defined for the BMC Impact Manager instanceand the SendEvent operation exits.
84
trueCause
The timeout element is defined by the built-in type int. The timeout element is part of the bmciis_send_Request message.
trueCause
The declaration for the element trueCause is shown below.
<xsd:element name=trueCause type=xsd:boolean/>
Used in the QueryModelPossibleRootCauses operation, the Boolean indicator trueCause specifies that, when set equal to true, the query traverses the provider
components for the possible root cause. In most instances, the root cause is equal to the true cause of the components status.
userName
The <wsdl:types> section contains the element declaration for the element userName.
<xsd:element name=userName nillable=true type=xsd:string/>
The userName element specifies the user name that is defined for a BMC Impact Manager instance. It is defined by the built-in type string. It is valid even when it carries no content. The userName element is part of the Connect_Request message.
Simple Types
Table 14 on page 85 lists the custom simple types that the ImpactManager.wsdl exposes and their corresponding built-in data types. Table 14 Simple Types
Built-in Data Type string string string string
Appendix A
85
IMMessageType
IMMessageType
The <wsdl:types> section contains the data definition for IMMessageType simple type.
<xsd:simpleType name=IMMessageType> <xsd:restriction base=xsd:string> <xsd:enumeration value=MSG_TYPE_NONE/> <xsd:enumeration value=MSG_TYPE_NEW_EVENT/> <xsd:enumeration value=MSG_TYPE_MOD_EVENT/> <xsd:enumeration value=MSG_TYPE_NEW_DATA/> <xsd:enumeration value=MSG_TYPE_OVERWRITE_DATA/> <xsd:enumeration value=MSG_TYPE_MOD_DATA/> </xsd:restriction> </xsd:simpleType>
The IMMessageType value specifies an enumeration of the types of messages that the web service client can exchange with the web service and the BMC Impact Manager instance. The messages contain the event or data object. The simple type IMMessageType has a restriction declaration that specifies that the built-in data type string must be used to specify its custom values, which are described in the following table.
Value MSG_TYPE_NONE MSG_TYPE_NEW_EVENT MSG_TYPE_MOD_EVENT MSG_TYPE_NEW_DATA MSG_TYPE_OVERWRITE_DATA Description empty message message contains a new event object message contains information for modifying an existing event object message contains a new data object message contains information for modifying an existing data object. If the data object does not already exist, then this operation creates it. message contains information for modifying an existing data object. The message type requires that the data_handle ID of the BMC Impact Manager instance is set to enable modification. It does not use the mc_udid identifier. If the data object does not already exist, then this operation fails.
MSG_TYPE_MOD_DATA
86
IMBufferType
IMBufferType
The <wsdl:types> section contains the data definition for the simple type IMBufferType.
<xsd:simpleType name=IMBufferType> <xsd:restriction base=xsd:string> <xsd:enumeration value=BMCII_BUFFER_MODE_DEFAULT/> <xsd:enumeration value=BMCII_BUFFER_MODE_NONE/> <xsd:enumeration value=BMCII_BUFFER_MODE_LOW/> <xsd:enumeration value=BMCII_BUFFER_MODE_HIGH/> </xsd:restriction> </xsd:simpleType>
The IMBufferType value specifies an enumeration of the types of buffering routines that are available for connection calls to the BMC Impact Manager instance. The simple type IMBufferType has a restriction declaration that specifies that the built-in data type string must be used to specify its custom values, which are described in the following table.
Value BMCII_BUFFER_MODE_ DEFAULT Description If the web services API cannot send the message to the BMC Impact Manager instance, the message is buffered in memory, but not saved to disk. The message is lost if the connection to the BMC Impact Manager instance is closed or if the BMC II Web Services server shuts down or terminates. This default value refers to the value that is defined in the startup configuration file of the BMC II Web Services server. If no value is defined in the configuration file, then BMCII_BUFFER_MODE_NONE is used. BMCII_BUFFER_MODE_ NONE No persistent buffering routine is available. The message is buffered in memory, but not saved to disk. Any events and data are lost if the BMC Impact Manager instance is unavailable. The message in the buffer is saved to a separate file on disk only if the web services API (SendEvent) cannot send the message. The message is saved on the disk until the web services API can complete its operation. If the web services API fails to complete its operation, the message is lost. BMCII_BUFFER_MODE_ HIGH The message in the buffer is saved immediately to a separate file, ensuring the message delivery. This buffer mode selection can be resource intensive because a copy of every message is saved to disk, even if the message is sent.
BMCII_BUFFER_MODE_ LOW
Appendix A
87
DataType
NOTE
The buffer resides on the C API interface with the BMC Impact Manager network.
DataType
The schema declaration file Basic Types.xsd contains the data definition of the simple type DataType.
<xsd:simpleType name=DataType> <xsd:restriction base=xsd:string> <xsd:enumeration value=BYTE/> <xsd:enumeration value=SHORT/> <xsd:enumeration value=INT/> <xsd:enumeration value=LONG/> <xsd:enumeration value=FLOAT/> <xsd:enumeration value=DOUBLE/> <xsd:enumeration value=STRING/> <xsd:enumeration value=BYTE_ARRAY/> <xsd:enumeration value=SHORT_ARRAY/> <xsd:enumeration value=INT_ARRAY/> <xsd:enumeration value=LONG_ARRAY/> <xsd:enumeration value=FLOAT_ARRAY/> <xsd:enumeration value=DOUBLE_ARRAY/> <xsd:enumeration value=STRING_ARRAY/> </xsd:restriction> </xsd:simpleType>
The simple type DataType has a restriction declaration that specifies that the built-in data type string must be used to specify its values. These values consist of built-in data types (BYTE, SHORT, INT, and so forth) and elements derived from complex types (BYTE_ARRAY, SHORT_ARRAY, INT_ARRAY, and so forth). Refer to value on page 93 for a description of the element value_element, defined from the complex type value, to see how the enumerated DataType values are implemented.
QueryMode
The <wsdl:types> section contains the data definition for the simple type QueryMode.
88
Complex Types
<xsd:simpleType name=QueryMode> <xsd:restriction base=xsd:string> <xsd:enumeration value=BMCII_EVENT_CLASSES/> <xsd:enumeration value=BMCII_DATA_CLASSES/> </xsd:restriction> </xsd:simpleType>
QueryMode defines which set of class definitions and respective subclasses are being queried: BMCII_EVENT_CLASSES or BMCII_DATA_CLASSES.
Complex Types
The ImpactManager.wsdl incorporates two sets of complex types. One set is derived from XML schema files. The other set is derived from custom data types that are specific to the ImpactManager.wsdl. The complex types are defined in the <wsdl:types> section and in the schema definition files Basic Types.xsd and the Event.xsd. The namespace that points to the Basic Types.xsd is imported into the Event.xsd file. The namespace that points to the Events.xsd is imported into the ImpactManager.wsdl. Table 15 on page 89 describes the custom complex types that the ImpactManager.wsdl file exposes. Table 15
ByteArray ShortArray IntArray LongArray FloatArray DoubleArray StringArray
Derived Element
Appendix A
89
Table 15
NameValue_element
NameValue
NameValue_element NameValueArray_ element subject Event_element cell_name cell_type cell_hostname port encryption_key trusted_servers
ArrayOf_CellInfo execution_fault
CellInfo_element IMFailure
90
NOTE
Arrays are similar to the C/C++ structure
composite types.
The arrays are derived from their related XML schema definitions. Each array is further defined by a sequence that consists of a single child element. The child element has the attributes minOccurs and maxOccurs, with the defined values of 0 and unbounded respectively.
ArrayOf_Byte
<xsd:element name=ByteArray type=btypes:ArrayOf_Byte/> <xsd:complexType name=ArrayOf_Byte> <xsd:sequence> <xsd:element name=byte_element minOccurs=0 maxOccurs=unbounded type=xsd:byte/> </xsd:sequence> </xsd:complexType>
ArrayOf_Short
<xsd:element name=ShortArray type=btypes:ArrayOf_Short/> <xsd:complexType name=ArrayOf_Short> <xsd:sequence> <xsd:element name=short_element minOccurs=0 maxOccurs=unbounded type=xsd:short/> </xsd:sequence> </xsd:complexType>
ArrayOf_Int
<xsd:element name=IntArray type=btypes:ArrayOf_Int/> <xsd:complexType name=ArrayOf_Int> <xsd:sequence> <xsd:element name=int_element minOccurs=0 maxOccurs=unbounded type=xsd:int/> </xsd:sequence> </xsd:complexType>
ArrayOf_Long
<xsd:element name=LongArray type=btypes:ArrayOf_Long/> <xsd:complexType name=ArrayOf_Long>
Appendix A
91
ArrayOf_Float
<xsd:element name=FloatArray type=btypes:ArrayOf_Float/> <xsd:complexType name=ArrayOf_Float> <xsd:sequence> <xsd:element name=float_element minOccurs=0 maxOccurs=unbounded type=xsd:float/> </xsd:sequence> </xsd:complexType>
ArrayOf_Double
<xsd:element name=DoubleArray type=btypes:ArrayOf_Double/> <xsd:complexType name=ArrayOf_Double> <xsd:sequence> <xsd:element name=double_element minOccurs=0 maxOccurs=unbounded type=xsd:double/> </xsd:sequence> </xsd:complexType>
ArrayOf_String
<xsd:element name=StringArray type=btypes:ArrayOf_String/> <xsd:complexType name=ArrayOf_String> <xsd:sequence> <xsd:element name=string_element minOccurs=0 maxOccurs=unbounded type=xsd:string/> </xsd:sequence> </xsd:complexType>
92
value
The schema definition file BasicTypes.xsd contains this data definition of value.
<xsd:element name=value_element type=btypes:value/> <xsd:complexType name=value> <xsd:choice> <xsd:element name=byte_value type=xsd:byte/> <xsd:element name=short_value type=xsd:short/> <xsd:element name=int_value type=xsd:int/> <xsd:element name=long_value type=xsd:long/> <xsd:element name=float_value type=xsd:float/> <xsd:element name=double_value type=xsd:double/> <xsd:element name=string_value type=xsd:string/> <xsd:element ref=btypes:ByteArray/> <xsd:element ref=btypes:ShortArray/> <xsd:element ref=btypes:IntArray/> <xsd:element ref=btypes:LongArray/> <xsd:element ref=btypes:FloatArray/> <xsd:element ref=btypes:DoubleArray/> <xsd:element ref=btypes:StringArray/> </xsd:choice> </xsd:complexType>
The complex type value can be any one of the defined child elements or referenced array elements within the <xsd:choice> and </xsd:choice> tags. These value choices consist of built-in data types and referenced array types.
NameValue
The schema definition file BasicTypes.xsd contains this data definition of the NameValue complex type.
<xsd:element name=NameValue_element type=btypes:NameValue/> <xsd:complexType name=NameValue> <xsd:sequence> <xsd:element name=name type=xsd:string/> <xsd:element name=value type=btypes:value/> <xsd:element name=value_type type=btypes:DataType minOccurs=0 maxOccurs=1/> </xsd:sequence> </xsd:complexType>
The NameValue complex type specifies how a value element is represented. It consists of sequence of child elements:
Appendix A
93
Data Type built-in type string the complex type value the simple type DataType
The value_type element has the attributes minOccurs and maxOccurs, with the defined values of 0 and 1 respectively.
ArrayOf_NameValue
The schema definition file BasicTypes.xsd contains this data definition of the ArrayOf_NameValue complex type.
<xsd:element name=NameValueArray_element type=btypes:ArrayOf_NameValue/> <xsd:complexType name=ArrayOf_NameValue> <xsd:sequence> <xsd:element name=NameValue_element minOccurs=0 maxOccurs=unbounded type=btypes:NameValue/> </xsd:sequence> </xsd:complexType>
The complex type ArrayOf_NameValue can contain multiple child NameValue_elements. The complex type Event extends the ArrayOf_NameValue type (see Event on page 95).
TableOf_NameValue
The schema definition file BasicTypes.xsd contains this data definition of the TableOf_NameValue complex type.
<xsd:element name=NameValueTable_element type=btypes:TableOf_NameValue/> <xsd:complexType name=TableOf_NameValue> <xsd:sequence> <xsd:element name=NameValueArray_element minOccurs=0 maxOccurs=unbounded type=btypes:ArrayOf_NameValue/> </xsd:sequence> </xsd:complexType>
The TableOf_NameValue complex type is defined by a sequence that consists of the child element NameValueArray_element, which is based on the complex type ArrayOf_NameValue. This child element has the attributes minOccurs and maxOccurs, with the respective values 0 and unbounded.
94 BMC ProactiveNet Performance Management Web Services Developer Guide
Event
The schema definition file Event.xsd contains this data definition of the Event complex type.
<xsd:element name=Event_element type=event:Event/> <xsd:complexType name=Event> <xsd:complexContent> <xsd:extension base=btypes:ArrayOf_NameValue> <xsd:sequence> <xsd:element name=subject type=xsd:string/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType>
The complex type Event extends the complex type ArrayOf_NameValue through its complexContent element. The complex type Event is a special subset of the values defined by the complex type ArrayOf_NameValue. It is delineated by a sequence element that consists of the child element subject of the built-in data type string. See also the message on page 75 for the description of an element that is derived from the Event complex type.
ArrayOf_Event
The schema definition file Event.xsd contains this data definition for the ArrayOf_Event complex type.
<xsd:element name=EventArray_element type=event:ArrayOf_Event/> <xsd:complexType name=ArrayOf_Event> <xsd:sequence> <xsd:element name=Event_element minOccurs=0 maxOccurs=unbounded type=event:Event> </xsd:sequence> </xsd:complexType>
The complex type ArrayOf_Event defines a collection of event elements. The standard content of the ArrayOf_Event complex type is defined by a sequence that consists of the element Event_element of the complex type Event. The ArrayOf_Event type can contain zero or more Event_elements.
Appendix A
95
The CellInfo complex type contains a sequence of child elements that identify the important attributes of the BMC Impact Manager instance or an Impact Integration instance. Each element must be declared in the sequence specified in the data definition. The information contained in the CellInfo complex type is similar to the information that the mcell.dir file defines. The child elements are defined as follows: Table 16
Element cell_name
cell_type
string
cell_hostname port
string unsignedInt
96
Table 16
Element
string
ArrayOf_CellInfo
The <wsdl:types> section describes the ArrayOf_CellInfo complex type. Its data definition is shown below.
<xsd:complexType name=ArrayOf_CellInfo> <xsd:sequence> <xsd:element minOccurs=0 maxOccurs=unbounded name=CellInfo_element type=tns:CellInfo/> </xsd:sequence> </xsd:complexType>
The complex type ArrayOf_CellInfo is collection of BMC Impact Manager or Impact Integration instances. Each instance is represented by the CellInfo_element child element. The type of the child element is based on the complex type CellInfo. It can contain zero or more CellInfo_elements. See also CellInfo_Array on page 66 for a description of an element that is derived from the ArrayOf_CellInfo complex type.
ClassDefInfo
The data definition of the complex type ClassDefInf is shown below.
<xsd:complexType name=ClassDefInfo> <xsd:sequence> <xsd:element name=class_parent_idx type=xsd:int/> <xsd:element name=class_child_cnt type=xsd:int/> <xsd:element name=class_name type=xsd:string/> <xsd:element name=child_list type=tns:ArrayOf_ClassDefInfo/> <xsd:element name=slots_count type=xsd:int/> <xsd:element name=slots_list type=tns:ArrayOf_SlotDefInfo/> </xsd:sequence> </xsd:complexType>
Appendix A
97
This definition uses the types integers, strings, and arrays to specify class and slot information, including the position of the selected class within the class hierarchy.
Element class_parent_idx class_child_cnt class_name child_list slots_count slots_list Description integer assigned to the selected parent class number of child classes name of the selected class an array of class definitions of children of the selected parent class number of slots in the selected class string description that specifies the slot name or names, the values for which the query returns. The slot names in the string are separated by commas, as in ','.
ArrayOf_ClassDefInfo
The data definition of the complex type ArrayOf_ClassDefInfo is shown below.
<xsd:complexType name=ArrayOf_ClassDefInfo> <xsd:sequence> <xsd:element maxOccurs=unbounded minOccurs=0 name=items type=tns:ClassDefInfo/> <xsd:element name=slots_list type=tns:ArrayOf_SlotDefInfo/> </xsd:sequence> </xsd:complexType>
SMComponent
The data definition of the complex type SMComponent is shown below.
<xsd:complexType name=SMComponent> <xsd:complexContent> <xsd:extension base=btypes:ArrayOf_NameValue/> </xsd:complexContent> </xsd:complexType>
ArrayOf_SMComponent
The data definition of the complex type ArrayOf_SMComponent is shown below.
98 BMC ProactiveNet Performance Management Web Services Developer Guide
<xsd:complexType name=ArrayOf_SMComponent> <xsd:sequence> <xsd:element maxOccurs=unbounded minOccurs=0 name=SMComponent_element type=tns:SMComponent/> </xsd:sequence> </xsd:complexType>
SlotDefInfo
The data definition of the complex type SlotDefInfo is shown below.
<xsd:complexType name=SlotDefInfo> <xsd:sequence> <xsd:element name=slot_name type=xsd:string/> <xsd:element name=slot_type type=xsd:string/> <xsd:element name=slot_rep_type type=xsd:string/> <xsd:element name=slot_flags type=xsd:string/> <xsd:element name=slot_def_val type=xsd:string/> </xsd:sequence> </xsd:complexType>
slot_rep_type
slot representation type that indicate what the slot type represents. Possible values include date and class. If the slot representation type is not specified, it is represented by an asterisk (*).
Appendix A
99
Element slot_flags
Description a Boolean indicator that indicates whether the slot has certain attributes. An uppercase character means that the attribute is true and does apply to the slot. A lower case character means that it is false and does not apply to the slot. The values are
s s s s s
r|R = read-only k|K = key p|P = parse d|D = dup_detect h|H = hidden
slot_def_value
ArrayOf_SlotDefInfo
The data definition of the complex type ArrayOf_SlotDefInfo is shown below.
<xsd:complexType name=ArrayOf_SlotDefInfo> <xsd:sequence> <xsd:element maxOccurs=unbounded minOccurs=0 name=SMComponent_element type=tns:SlotDefInfo/> </xsd:sequence> </xsd:complexType>
CStatus
The data definition of the complex type CStatus is shown below.
<xsd:complexType name=CStatus> <xsd:sequence> <xsd:element name=cmpStatus type=xsd:string/> <xsd:element name=impStatus type=xsd:string/> <xsd:element name=manStatus type=xsd:string/> <xsd:element name=subStatus type=xsd:string/> </xsd:sequence> </xsd:complexType>
GetEventsResponse
The data definition of the complex type GetEventsResponse is shown below.
<xsd:complexType name=GetEventsResponse> <xsd:sequence>
100
GetQueryResultResponse
The data definition of the complex type GetQueryResultResponse is shown below.
<xsd:complexType name=GetQueryResultResponse> <xsd:sequence> <xsd:element name=response type=event:ArrayOf_Event/> <xsd:element name=num_of_events type=xsd:int/> </xsd:sequence> </xsd:complexType>
StateChangeType
The data definition of the complex type StateChangeType is shown below.
<xsd:complexType name=StateChangeType> <xsd:sequence> <xsd:element name=bCompChange type=xsd:boolean/> <xsd:element name=bCompDelete type=xsd:boolean/> <xsd:element name=bRelChange type=xsd:boolean/> <xsd:element name=bRelDelete type=xsd:boolean/> <xsd:element name=bAll type=xsd:boolean/> </xsd:sequence> </xsd:complexType>
execution_fault
The data definition of the complex type execution_fault is shown below.
<xsd:element name="execution_fault"> <xsd:complexType> <xsd:sequence> <xsd:element name="IMFailure" nillable="true" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element>
Execution_fault carries a string message that describes the operation executing errors. The execution_fault is generated by the BMC II Web Services server and thrown to the client through the web service infrastructure.
Appendix A
101
102
Appendix
B
104 104 104 105 107 108 109 110 112 113 115 117 118 120 122 124 126 128 129 131 133 135 137 139 141 142 144 145 147 148
103
This Appendix describes the set of API operations currently defined by the Impact Manager port type. The following topics are described: PortType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AckEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EndQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetCellInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetFilterNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetQueryResultCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryClassDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentsByCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryComponentsByStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryEventByID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryEvents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryEventsByDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryModelImpact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QueryModelPossibleRootCauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RegisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RetrieveQueryResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SendEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SetMaintenanceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SetManualStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UnregisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix B BMC Impact Integration Web Services API operations
PortType
PortType
The port type Impact Manager groups the operations and the underlying messages of the BMC Impact Integration Web Services.
Operations
The Impact Integration Web Service communicates via request/response exchanges. Accordingly, each operation contains an input element followed by an output element.
AckEvents
After a GetEvents call, the polling client is responsible for calling AckEvents to notify the BMC II Web Services server that it has received the events. The server removes the forwarded events from its local cache. The AckEvents call is required for both reliable and non-reliable subscriptions.
WARNING
The value of the num_of_events input parameter must equal the number of events received from the GetEvents call. If not, lost events or duplicate events could have occurred.
104
Connect
context num_of_events
In In
tns:context tns:num_of_events
Connect
The Connect operation allows the BMC II Web Services to connect with specific instances in the BMC Impact Manager network. The Connect operation is required when you want to send events to specific instances.
NOTE
The query operations use their own connection protocol, which is distinct from the Connect operation.
Appendix B
105
Connect
See IMBufferType on page 87 for a description of the buffer types. connectionId Out tnc:connectionId long integer that specifies the connection handle
106
Disconnect
Disconnect
The Disconnect operation sends a request to the BMC II Web Services server, seeking to gracefully disconnect from the connected instance or instances.
Appendix B
107
EndQuery
EndQuery
The EndQuery operation terminates the query cycle. The EndQuery operation is invoked by the client after it has obtained the query results through the RetrieveQueryResults. In the EndQuery operation, the client sends the ID associated with the query cycle back to the BMC II Web Services server, notifying the server that the query has terminated.
WARNING
You must invoke the EndQuery operation to terminate the query cycle. Otherwise, the query ID (resultHandle) is not cleaned up in the BMC II Web Services server, and the connection with the specified cell is not closed.
108
GetCellInfo
GetCellInfo
The GetCellInfo operation enables the Web Service client to identify and obtain information about the BMC Impact Manager instances that are connected to the BMC II Web Services server. You do not have to be connected (Connect) to a BMC Impact Manager instance before you invoke this operation.
Appendix B
109
GetEvents
instance or integration name host name of the system where the instance or integration is installed port number encryption key type of instance or integration
GetEvents
The GetEvents operation is a polling call that the client initiates to receive a specified number of a certain event type from the BMC Impact Manager network. You do not have to be connected (Connect) to an instance to get events, but you do have to invoke a subscription request (Subscribe).
110
GetEvents
context
In
tns:context
Appendix B
111
GetFilterNames
Name num_of_events
Direction In/Out
Description As the input argument, this is the integer that specifies the number of events the client seeks to receive per polling call. As the output argument, it indicates the number of events that the server is able to return. complex type that specifies the name of one or more events that are being returned in response to the Web Service clients polling call
response
Out
event:EventArray_ element
GetFilterNames
The GetFilterNames operation enables the Web Service client to discover the range of selector names that it can subscribe to. The BMC II Web Services server returns a list of selectors that are currently defined in its selector file. You do not have to invoke the Connect operation to invoke the GetFilterNames operation.
112
GetQueryResultCount
GetQueryResultCount
The GetQueryResultCount operation tallies the total number of events or data objects that the BMC II Web Services server has retrieved in response to the query. In this operation, the client sends the query ID and a timeout duration to the BMC II Web Services server. The server responds with the total count of events or data objects that are available to the query.
Appendix B
113
GetQueryResultCount
timeout
In
tns:timeout
resultCount
Out
tns:long_Response
114
QueryClassDefinitions
QueryClassDefinitions
The QueryClassDefinitions operation provides two different types of queries of a specified BMC IM instance. One query option retrieves the class and slot definitions of a specific base class and its subclasses. The second query option retrieves the class and slot definitions of a specified class. In either case you must choose whether you are querying the event or data classes. And both queries return their data in the form of a flat array.
Appendix B
115
QueryClassDefinitions
baseClass
In
tns:baseClass
116
QueryComponent
Name classOnly
Direction In
Description Boolean indicator (0, 1) that restricts the query to a specified class name or expands the query to include the base class and its subclasses Enter 0 if you are querying a base class and its subclasses. Enter 1 if you are querying a specified class only (the className parameter).
classDefs
Out
tns:ClassDefInfo_ array
QueryComponent
The QueryComponent operation retrieves the component data attributes of a specified component object.
Appendix B
117
QueryComponentEvents
resultCount
Out
resultCount
QueryComponentEvents
The QueryComponentEvents operation sends a request to retrieve direct and impact events associated with a specific component. You have the option of retrieving only impact events.
118
QueryComponentEvents
Appendix B
119
QueryComponentStatus
slotsList
In
tns:slotsList
resultHandle
Out
resultHandle
resultCount
Out
resultCount
QueryComponentStatus
The QueryComponentStatus operation retrieves a components status, as defined by its computed component status: status, self_status, computed_status, impact_status, and manual_status. It returns the following default slot values:
s s s s s s
120
QueryComponentStatus
resultHandle
Out
resultHandle
resultCount
Out
resultCount
Appendix B
121
QueryComponentsByCondition
QueryComponentsByCondition
The QueryComponentsByCondition operation retrieves 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. The criteria are a logical combination of expressions that define the slots associated with the component. This query can span multiple cells to retrieve the specified service model components.
122
QueryComponentsByCondition
resultHandle
Out
resultHandle
resultCount
Out
resultCount
Appendix B
123
QueryComponentsByStatus
QueryComponentsByStatus
The QueryComponentsByStatus operation queries for service components that
s
have MC_SM_COMPONENT_STATUS values which match, are less than or equal to, or are greater than or equal to the specified status parameters; and belong to the specified base class or subclass
This query can span multiple cells to retrieve the specified service model components.
124
QueryComponentsByStatus
Appendix B
125
QueryData
Name hStatus
Direction In
Description string type value that indicates the highest MC_SM_COMPONENT_STATUS value to be selected If you enter only a value for the highest status, the call selects statuses that are equal to or less than the indicated highest value. If you specify a range by entering values for both the lowest status and the highest status, then the call selects status values that are equal to or greater than the lowest status and equal to or less than the highest status. For example, if you specify that the lowest
status is equal to UNKNOWN and highest status is equal to MINOR, then the call selects components with statuses UNKNOWN, OK, INFO, WARNING, and MINOR.
baseClass getSubClasses In In tns:baseClass tns:getSubClasses string type that indicates the base class to be selected. Its default is BMC_AssetBase. a Boolean indicator that, when set equal to true, selects subclasses of the designated base class. If bSubclasses is set equal to false, then the selection is restricted to the base class string description that specifies the slot name or names, the values for which the query returns. The slot names in the string are separated by commas, as in ','. string type that contains the ID returned by the servers response to the initial query request. This ID is attached to all query requests in this cycle. xsd:long type that defines the total number of events or data objects that have been retrieved by the BMC II Web Services server in response to the client query
slotsList
In
tns:slotsList
resultHandle
Out
resultHandle
resultCount
Out
resultCount
QueryData
The QueryData operation is a flexible query operation that the Web Service client uses to define its own query to retrieve data. In this operation, the client connects with a specific BMC Impact Manager instance and starts a query for data. The BMC II Web Services server returns an ID that is used to identify all related queries in the query cycle.
126
QueryData
The client can construct its own query contents to retrieve and manipulate data such as delete, modify data, and so on. The contents of the query input element have to be a valid Impact Manager cell communication command for data manipulation.
NOTE
The syntax of the communication command is not within the scope of this guide. However, BMC II Web Services provides examples in client samples to demonstrate use cases. The integration developer needs to be familiar with cell communication commands to construct the query.
Appendix B
127
QueryEventByID
imname resultHandle
In Out
tns:imname resultHandle
resultCount
Out
resultCount
QueryEventByID
The QueryEventByID operation is one of the query operations that the Web Service client can request. In this operation, the client connects with a specific BMC Impact Manager instance and queries for a specific BMC Impact Manager event using its BMC Impact Manager universal event ID (mc_ueid). The BMC II Web Services server returns an ID that is used to identify all related queries in the query cycle.
128
QueryEvents
resultCount
Out
resultCount
QueryEvents
The QueryEvents operation is a flexible query operation that the Web Service client can use to define its own query to retrieve events. In this operation, the client connects with a specific BMC Impact Manager instance and starts a query for events. The BMC II Web Services server returns an ID that is used to identify all related
Appendix B
129
QueryEvents
queries in the query cycle. The client can construct its own query contents to retrieve and manipulate events, such as delete, modify events, and so on. The contents of the query input element have to be a valid Impact Manager (cell) communication command for event manipulation.
NOTE
The syntax of the communication command is not within the scope of this guide. However, BMC II Web Services provides examples in client samples to demonstrate use cases. The integration developer needs to be familiar with cell communication commands to construct the query.
130
QueryEventsByDate
imname resultHandle
In Out
tns:imname resultHandle
resultCount
Out
resultCount
QueryEventsByDate
The QueryEventsByDate operation is one of the query operations that the Web Service client can request. In this operation, the client connects with a specific BMC Impact Manager instance and queries for events that are grouped within a specific message class and that have occurred within a specific date range. The BMC II Web Services server returns an ID that is used to identify all related queries in the query cycle.
Appendix B
131
QueryEventsByDate
endDate
In
tns:endDate
In In In
resultHandle resultCount
Out Out
resultHandle resultCount
132
QueryModelImpact
QueryModelImpact
The QueryModelImpact operation retrieves possible consumer components of the specified component. Consumer components are the components that can receive the impacts of the specified component. It returns values (if available) for the following default slots:
s s s s s
This query can span multiple cells to retrieve the specified service model components.
Appendix B
133
QueryModelImpact
QueryModelImpact
<xsd:element name="QueryModelImpact"> <xsd:complexType> <xsd:sequence> <xsd:element name="imname" nillable="true" type="xsd:string"/> <xsd:element name="componentId" nillable="true" type="xsd:string" /> <xsd:element name="slotsList" nillable="true" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="QueryResultHandle_output"> <xsd:complexType> <xsd:sequence> <xsd:element name="resultHandle" nillable="true" type="xsd:string"/> <xsd:element name="resultCount" type="xsd:long" /> </xsd:sequence> </xsd:complexType> </xsd:element>
resultHandle
Out
resultHandle
resultCount
Out
resultCount
134
QueryModelPossibleRootCauses
QueryModelPossibleRootCauses
The QueryModelPossibleRootCauses operation uses a Boolean TrueCause input parameter to retrieve a component or components that have either an immediate, direct relationship with the specified component or that have statuses which were propagated to the component. It returns values (if available) for the following default slots:
s s s s s
This query can span multiple cells to retrieve the specified service model components.
Appendix B
135
QueryModelPossibleRootCauses
136
RegisterStateChange
Name trueCause
Direction In
Description Boolean indicator that traverses the provider components of the specified component. If set equal to True, it returns: Possible Related Problems: restricts the search to components with immediate, direct relationships to the specified component. If set equal to False or left blank, it returns: Causal Components: extends the search beyond the immediate, direct relationships to include components whose statuses were propagated to the specified component to cause the impact.
See also the BMC Impact Explorer GUI, specifically the Causes tab in the Service Component detail pane.
resultHandle Out resultHandle string type that contains the ID returned by the servers response to the initial query request. This ID is attached to all query requests in this cycle. xsd:long type that defines the total number of events or data objects that have been retrieved by the BMC II Web Services server in response to the client query
resultCount
Out
resultCount
RegisterStateChange
The RegisterStateChange operation registers your integration with a SIM cell, which enables you to receive state change events.
Appendix B
137
RegisterStateChange
138
RetrieveQueryResults
Name changeType
Direction In
Description indicates an array of possible state change event types. Valid values include
s s s s s
You can use the conditional AND operator && to combine two types: for example RELATIONSHIP_CHANGE && RELATIONSHIP_DELETE registrationID Out tns:regID integer that is assigned to this registration request
RetrieveQueryResults
The RetrieveQueryResults operation retrieves some or all of the results that are returned for a query. The RetrieveQueryResults operation returns two parameters in its response message.
Appendix B
139
RetrieveQueryResults
In In
num_of_results In/Out
tns:num_of_results
results
Out
bypes:NameValue Table_element
140
SendEvent
SendEvent
The SendEvent operation sends a message containing an event to the connected BMC Impact Manager instance. Along with the message, the SendEvent operation forwards the originating connection handle ID, and the timeout duration specifying the time between connection attempts. You must invoke the Connect operation before you can invoke the SendEvent operation.
NOTE
To stop sending events, you can stop issuing the SendEvent operation. You do not have to disconnect (Disconnect) from the BMC Impact Manager instance(s).
Appendix B
141
SetMaintenanceMode
timeout
In
tns:timeout
messageClass
In
tns:messageClass
messageType
In
tns:messageType
See IMMessageType on page 86 for a description of the value values. response Out response literal or string message that the BMC II Web Services server sends as a reply to the request from the Web Service client. This element of type string is valid even when it carries no content.
SetMaintenanceMode
The SetMaintenanceMode operation sends a request to place a specified component in maintenance mode.
142
SetMaintenanceMode
Appendix B
143
SetManualStatus
Name setOrCleared
Direction In
Description Boolean indicator (true/false) that indicates whether the specified component is available to have its maintenance mode set string description of the maintenance mode string that describes the reason for setting or clearing the current maintenance mode integer that identifies a C API error code
In In Out
SetManualStatus
The SetManualStatus operation sends a request to set a designated manual status on the specified component.
144
Subscribe
Subscribe
Clients can call the Subscribe operation to guarantee event delivery. When sending the subscription request, the client needs to know whether you want a reliable subscription or an non-reliable subscription. The life span of a reliable subscription is started when the Subscribe() call succeeds and ends when the client calls Unsubscribe(). The life span of an unreliable subscription ends when the client calls Unsubscribe() or the BMC II Web Services server is terminated.
Appendix B
145
Subscribe
For a reliable subscription, when BMC II Web Services is terminated, the client subscribe information is saved to the persistent file. When BMC II Web Services starts again, the client can continue to get events from this reliable subscription. The EventReceiverManager.dat persistent file is located under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/log directory. The SubscriptionManager.dat file under the same directory stores the descriptions for an unreliable subscriptions.
146
UnregisterStateChange
context reliable
In In
tns:context tns:reliable
UnregisterStateChange
The UnregisterStateChange operation removes the registration ID assigned to the request to receive state change events and thus stops your integration from receiving state change events.
Appendix B
147
Unsubscribe
Unsubscribe
The Unsubscribe operation enables the Web Service client to stop its subscription to specified events. If connected (Connect) to BMC IM instances, you do not have to disconnect (Disconnect) to stop receiving events.
148
Unsubscribe
context
In
tns:context
Appendix B
149
Unsubscribe
150
Chapter
When configuring your BMC II Web Services server, you can specify the address location (URI) where the web service client or clients can access it. At runtime, this address is read by the BMC II Web Services server and is made available through the soap:address element of the <wsdl:service> section. For example, if your BMC II Web Services server is configured to start at the endpoint http://abc:6070/imapi, then the ImpactManager.wsdl reveals the address location as a value of the <soap:address> element.
<soap: address location:http://abc:6070/imapi/>
Appendix C
151
152
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 http://www.w3.org/TR/ws-gloss/. 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. .load file A file that specifies the order in which a directorys 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.
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.
Glossary
153
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
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 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.
154
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
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. 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 See BMC Impact Integration (BMC II) product.
Glossary
155
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 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. 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.
156
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 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
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. CI See Configurable Instance. Configurable Instance
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
Glossary
157
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
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. 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.
158
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
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. 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.
Glossary
159
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 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 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 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.
160
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 instances 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.
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. heartbeat interval The time between heartbeats; the period of the heartbeat.
Glossary 161
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
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. 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. 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
162
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
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 ImWebServices.conf 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 ImWebServices.conf 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. mcell.conf file The configuration file that contains configuration options for a BMC Impact Manager instance (cell). It is in the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory.
Glossary
163
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.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 $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etcdirectory. 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 operations 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.
164
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 email message or SNMP trap that is sent when the program detects a problem that triggers an alert. 2. A type of policy.
O
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. 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. porting The process of translating or converting software to run in a different operating environment.
Glossary
165
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
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.
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. 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.
166
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
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. ImWebServices.conf 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 $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc. 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 instances 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 instances 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. 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 components status. State change events never participate in component status computation.
Glossary
167
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
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.
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.
168
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
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. 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.
Glossary
169
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
IIWSGatewayserver 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 1859. It receives events and messages from BMC Impact Manager instances and stores them in a buffer. The IIWSGatewayserver 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 IIWSGatewayserver entry. To connect with the BMC Impact Manager network, you must also enter the IIWSGatewayserver information in the mcell.dir file of BMC Impact Manager instance to which you are connecting. See also mcell.dir file.
170
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 52 $doselector function, description 53 $Format function 54 $function_name function 52 $GmtTime function 54 $HostName function 52 $LocalTime function 54 $slotMissing function 54 $slotPresent function 53 $TimeT function 54 %s 54 BMC Impact Integration Web Services Developers Kit 43 BMC Impact Integration Web Services server 43 adminstration 44 selector processing 45 BMC Impact Manager 151 BMC Software, contacting 2 BMCII_BUFFER_MODE_DEFAULT, description 87 BMCII_BUFFER_MODE_HIGH, description 87 BMCII_BUFFER_MODE_LOW, description 87 BMCII_BUFFER_MODE_NONE, description 87 bmcii_loadSelectorSet function, failure 46 buffering buffer, maximum size 59 MessageBufferReconnectInterval parameter 59 MessageBufferSize parameter 59 reconnect interval 59 bufferType, element description 66 ByteArray derived complex type 89
A
administration BMC Impact Integration Web Services server 44 editing iiws.selector 58 iiws.conf file 58 iiws.selector file 44 ArrayOf_Byte, element description 91 ArrayOf_CellInfo, element description 97 ArrayOf_ClassDefInfo, element description 98 ArrayOf_Double, element description 92 ArrayOf_Event, element description 95 ArrayOf_Float, element description 92 ArrayOf_Int, element description 91 ArrayOf_Long, element description 91 ArrayOf_NameValue, element description 94 ArrayOf_Short, element description 91 ArrayOf_SlotDefInfo, element description 100 ArrayOf_SMComponent, element definition 98 ArrayOf_String, element description 92 audience presumed knowledge 43 roles 43
C
cell_hostname element, description 96 cell_name element, description 96 cell_type element, description 96 CellInfo 96 cellInfo_Array element description 66 parameter 110 ChangeDate parameter, message selector set header 49 changeType parameter 139 ClassDefInfo, element description 97 classDefInfo_Array element description 67 parameter 117 classDefInfo_element, description 67 classDefs parameter 117 classes, specifying in translation maps 52 className element description 67 parameter 116 classNames element description 67 parameter 132 classOnly element description 68
B
baseClass element description 66 parameter 116, 126 BasicTypes.xsd 63 BMC Developer Connection 15 BMC Impact Integration Web Services APIs 43
Index
171
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
parameter 117 comment element description 68 parameter 144, 145 componentCauseId element description 68 componentId element description 69 parameter 118, 120, 134, 136, 143, 145 componentStatus element description 69 parameter 145 componentStatusId element description 69 parameter 121 condition element description 69 parameter 123 configuring iiws.conf 59 Connect operation 105 connecting, maximum reconnect interval 59 connection element description 70 connectionId element description 70 parameter 107, 142 context element description 70 parameter 105, 111, 147, 149 context_nio element description 71 CStatus element description 100 Cstatus_element element description 71 CStatusHigh element description 71 CStatusLow element description 72 custom complex types ArrayOf_CellInfo 97 ArrayOf_ClassDefInfo 98 ArrayOf_SlotDefInfo 100 ArrayOf_SMComponent 98 CellInfo 96 ClassDefInfo 97 CStatus 100 GetEventsResponse 100 GetQueryResultResponse 101 SlotDefInfo 99 SMComponent 98 StateChangeType 101 customer support 3
D
data types arrays 90 complex 89 mapping to other languages 102 overview 63 simple 85 data types, XSD imported schemas 63 DataType element description 88 deleteBuffer element description 72 parameter 107 Description parameter in message selector header 50 in message selector set header 49 Disconnect operation 107 DoubleArray derived complex type 89
E
element descriptions general 64 summary table 64 embedding message selectors 46 Enable parameter in message selector header 50 in message selector set header 49 encryption_key element, description 97 endDate element description 72 parameter 132 EndQuery operation 108 errorCode element description 73 parameter 144, 145 Event complex type, description 95 Event.xsd 63 Event_element derived complex type 90 EventArray_element derived complex type 90 eventId element description 73 parameter 129
F
FailOnMissingSlot message selector header parameter 50 failure matching 50 selection 50 filterName
172
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
element description 73 parameter 105, 111, 113, 147, 149 FloatArray derived conplex type 89 formatting %, using in message selectors 54 message selectors and message selector sets 48 FormatVersion parameter, in message selector set header 49 functions $ClassName 52 $doselector 53 $Format 54 $function_name 52 $GmtTime 54 $HostName 52 $LocalTime 54 $slotMissing 54 $slotPresent 53 $TimeT 54 in message selectors 51 slot.slotname 52 IMBufferType custom values 87 element description 87 imFailure element description 74 IMMessageType custom values 86 element description 86 imname element description 75 parameter 120, 125, 129, 131, 132, 143, 145 Impact Manager port type, definition 104 IntArray derived complex type 89
L
long_Response element description 75 parameter 114 LongArray derived complex type 89 lStatus parameter 125
G
GetCellInfo operation 109 GetEvents operation 110 GetEventsResponse complex type, description 100 GetEventsResponse_element element description 74 GetFilterNames operation 112 GetQueryResultCount operation 113 GetQueryResultResponse complex type, description 101 GetQueryResultResponse_element element description 74 getSubclasses element description 74 parameter 126
M
mcell.dir description 62 editing 62 message element description 75 parameter 142 message buffer capacity 59 message propagation MessageBufferKeepSent parameter 59 MessageBufferKeepWait parameter 59 MessageBufferReconnectInterval parameter 59 MessageBufferResendCount parameter 59 MessageBufferSize parameter 59 message selectors characteristics 46 content 51 embedding 53 embedding with $doselector 46 file, characteristics 46 formatting 48 header requirement 50 header sample 51 message selector set header 48 name 50 operators 55 parameters, header 50 parameters, set header 49 set header requirement 48 set header sample 49 sets, description 46
H
host names, specifying in message selectors 52 hStatus parameter 126
I
iiws.conf, configuration parameters 59 iiws.selector file 44, 58 IIWSGatewayserver event listener port 24 ImapiTypes.xsd 63
Index
173
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
sets, formatting 48 sets, headers 48 sets, naming 46 slots, missing 50 syntax rules 46 time, specifying settings 54 MessageBufferKeepSent 59 MessageBufferKeepSent configuration parameter 59 MessageBufferKeepWait configuration parameter 59 MessageBufferReconnectInterval configuration parameter description 59 MessageBufferResendCount configuration parameter 59 MessageBufferSize configuration parameter description 59 messageClass element description 76 parameter 142 messageID element description 76 messageType element description 76 parameter 142 modeToSet element description 77 parameter 144 MSG_TYPE_MOD_DATA, description 86 MSG_TYPE_MOD_EVENT, description 86 MSG_TYPE_NEW_DATA, description 86 MSG_TYPE_NEW_EVENT, description 86 MSG_TYPE_NONE, description 86 MSG_TYPE_OVERWRITE_DATA, description 86 parameter 120 operations Connect 105 Disconnect 107 EndQuery 108 GetCellInfo 109 GetEvents 110 GetFilterNames 112 GetQueryResultCount 113 QueryClassDefinitions 115 QueryComponent 117 QueryComponentEvents 118 QueryComponentsByCondition 122 QueryComponentsByStatus 124 QueryComponentStatus 120 QueryData 126 QueryEventByID 128 QueryEventsByDate 131 QueryModelImpact 133 QueryModelPossibleRootCauses 135 RegisterStateChange 137 RetrieveQueryResults 139 SendEvent 141 SetMaintenanceMode 142 SetManualStatus 144 Subscribe 145 UnregisterStateChange 147 Unsubscribe 148
P
parameters ChangeDate 49 Description 49 Enable 49, 50 FailOnMissingSlot 50 FormatVersion 49 message selector set header list 49 MessageBufferKeepWait 59 MessageBufferReconnectInterval 59 MessageBufferResendCount 59 MessageBufferSize 59 PersistencyCleanupGarbageThreshold 60 PersistencyCleanupSizeThreshold 60 PersistencyDisconnectRemoveMessages 60 PersistencyEnabled 60 PersistencyFileName 60 PersistencyLevel 60 SelectorHeader 50 SelectorSetName 49 Version 49 password element description 78 PersistencyCleanupGarbageThreshold configuration parameter 60
N
Name_Value_element derived complex type 90 NameValue child elements 93 element description 93 NameValue_Array_element derived complex type 90 nameValueTable_element parameter 140 NameValueTable_element derived complex type 90 num_of_components element description 77 num_of_events element description 77 parameter 105, 112 num_of_results element description 78 parameter 140
O
onlyImpacted element description 78
174
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
PersistencyCleanupSizeThreshold configuration parameter 60 PersistencyDisconnectRemoveMessages configuration parameter 60 PersistencyEnabled configuration parameter 60 PersistencyFileName configuration parameters 60 PersistencyLevel configuration parameter description 60 port element, description 96 ports IIWSGatewayserver event listener 24 printf function 54 product support 3 parameter 139, 148 reliable element description 80 parameter 147 response parameter 112 responseId parameter 142 resultCode element description 80 parameter 148 resultCount parameter 114 resultHandle element description 80 parameter 109, 114, 120, 123, 126, 129, 131, 132, 137 RetrieveQueryResults operation 139 retrieveResultHandle element description 81 parameter 140
Q
query element description 78 parameter 131 QueryClassDefinitions operation 115 QueryComponent operation 117 QueryComponentEvents operation 118 QueryComponentsByCondition operation 122 QueryComponentsByStatus operation 124 QueryComponentStatus operation 120 QueryData operation 126 QueryEventByID operation 128 QueryEventsByDate operation 131 QueryMode element description 88 queryMode parameter 116 QueryMode_element element description 79 QueryModelImpact operation 133 QueryModelPossibleRootCauses operation 135
S
schemas, imported 63 SecurityToken element description 81 SelectorName message selector header parameter 50 selectors iiws.selector file 58 in subscription requests 45 overview 44 selectorset_name.message selector file 46 SelectorSetName message selector set header parameter 49 SendEvent operation 141 ServerName element description 81 serverName parameter 138 SetMaintenanceMode operation 142 SetManualStatus operation 144 SetOrCleared element description 82 setOrCleared parameter 144 ShortArray derived complex type 89 slot.slotname function 52 SlotDefInfo element description 99 SlotDefInfo_Array element description 82 SlotDefInfo_element element description 82
R
regID element description 79 RegisterStateChange operation 137 registrationID
Index
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
slots in message selectors 51 missing from message selectors 50 selecting, by value 52 SlotsList element description 82 slotsList parameter 120, 123, 126, 132, 134, 136 SMComponent element description 98 SMComponent_element element description 83 SMComponentArray_element element description 83 source-code generator compiling ImpactManager.wsdl 32 StartDate element description 83 startDate parameter 132 StartIndex element description 84 startIndex parameter 140 StateChangeType element description 101 StateChangeType_element element description 84 strftime 54 string_Response parameter 120, 123, 126, 132, 137 StringArray derived complex type 89 Subscribe operation 145 support, customer 3
U
UnregisterStateChange operation 147 Unsubscribe operation 148 userName element description 85
V
value complex type, description 93 value_element derived complex type 90 Version, message selector set header parameter 49
W
Web services client programming language 31 summary of steps 32
X
XSD data types imported schemas 63
T
TableOf_NameValue element description 94 technical support 3 TIBCO platform 18 time, using in message selectors 54 time_t, in message selector files 54 timeout element description 84 parameter 114, 140, 142 translation class names, specifying 52 host names, specifying 52 trueCause element description 85 parameter 137 trusted_servers element, description 97
176
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 prsente convention ainsi que les documents qui sy rattachent soient rdigs 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.
OpenSSl License
Copyright (C) 1995 Tim Hudson (tjh@mincom.oz.au) All rights reserved. This package is documentation for the SSLeay implementation that was written by Eric Young (eay@mincom.oz.au). The documentation was written by Tim Hudson (tjh@mincom.oz.au). 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 (tjh@mincom.oz.au) 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.
Notes
*209476*