Impact Integration Web Services Server Developer Guide

www.bmc.com

BMC Impact Integration Web ServicesDeveloper Guide

Supporting

BMC Impact Integration Web Services 8.6

July 2011

Contacting BMC Software

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

United States and Canada

Address BMC SOFTWARE INC2101 CITYWEST BLVDHOUSTON TX 77042-2827 USA

Telephone 713 918 8800 or800 841 2031

Fax 713 918 8000

Outside United States and Canada

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

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

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

http://www.bmc.com

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

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

telephone numbers

Support by telephone or e-mail

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

Before contacting BMC

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

■ product information

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

■ operating system and environment information

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

maintenance level

■ sequence of events leading to the issue

■ commands and options that you used

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

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

3

http://www.bmc.com/support

mailto:[email protected]

License key and password information

If you have questions about your license key or password, use one of the following methods to get assistance:

■ Send an e-mail message to [email protected].

■ Use the Customer Support website at http://www.bmc.com/support.

4 BMC ProactiveNet Performance Management Web Services Developer Guide

mailto:[email protected]

http://www.bmc.com/support

ContentsChapter 1 Introduction 15

Intended audience for web services development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Security considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Internationalization considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Atrium service registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Registering BMC II Web Services with the BMC UDDI server . . . . . . . . . . . . . . . 17

Overview of BMC Impact Integration Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Platform and required tools or components for development . . . . . . . . . . . . . . . . 18

BMC II Web Services overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19BMC II Web Services access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Features of the BMC II Web Services server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Components of the BMC II Web Services server . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 2 Securing web services 25

Securing BMC II Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Default keystore files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Modify the security configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Guidelines for choosing client interfaces 31

Client components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Programming language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Guidelines for building a client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Generating the client proxy code (client stubs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Summary of BMC II Web Services operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33BMC II Web Services client sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Implementing the BMC II Web Services operations . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 4 BMC Impact Integration Web Services server Administration 43

Starting server instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44How the BMC II Web Services server reads selector files and parameters. . . . . . . . . 44Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Contents 7

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

mcell.dir file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Appendix A BMC Impact Integration Web Services Data Types 63

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Imported schema definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

baseClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66bufferType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66CellInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66ClassDefInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67ClassDefInfo_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67className . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67classNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67classOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68componentCauseId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68componentId. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69componentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69componentStatusId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70connectionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70context_nio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Cstatus_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71cStatusHigh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71cStatusLow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72deleteBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72endDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72errorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73eventID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73filterName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73GetEventsResponse_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74GetQueryResultResponse_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74getSubclasses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74imFailure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74imName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75long_Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75messageClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76messageID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76messageType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76modeToSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77num_of_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77num_of_events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77num_of_results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

8 Book Title

onlyImpacted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78QueryMode_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79regID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79reliable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80resultCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80resultHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80retrieveResultHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81securityToken. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81serverName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81setOrCleared. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82SlotDefInfo_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82SlotDefInfo_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82slotsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82SMComponent_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83SMComponentArray_element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83startDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83startIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84StateChangeType_element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84trueCause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85userName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Simple Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85IMMessageType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86IMBufferType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87DataType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88QueryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Complex Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Arrays from Built-In Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Value Choices, Name-Value Pairs, and Custom Complex Types . . . . . . . . . . . . . 92Custom 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

PortType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

AckEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107EndQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108GetCellInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109GetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110GetFilterNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112GetQueryResultCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113QueryClassDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115QueryComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117QueryComponentEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118QueryComponentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Contents 9

QueryComponentsByCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122QueryComponentsByStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124QueryData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126QueryEventByID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128QueryEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129QueryEventsByDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131QueryModelImpact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133QueryModelPossibleRootCauses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135RegisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137RetrieveQueryResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139SendEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141SetMaintenanceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142SetManualStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145UnregisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Unsubscribe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Appendix C BMC Impact Manager Service 151

Glossary 153

Index 171

10 Book Title

FiguresBMC II Web Services server overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Structure of message selector set file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Sample message selector set header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Figures 11

TablesBMC II Web Services server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Details for the iiwsssl.jks keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Details for the iiwscacerts.jks keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Details for the iiwsssl.cer keystore file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26BMC II Web Services server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Components that support a receive interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Message selector set header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Message selector header contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Message selector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Message selector operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Keyword descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Complex Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89CellInfo Child Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Tables 13

C h a p t e r 1
1 Introduction
This chapter introduces the BMC Impact Integration Web Services Developers Guide.

Intended audience for web services development

The audience for the BMC Impact Integration Web Services Developer Guide is experienced developers who are knowledgeable about web services technologies: XML; Simple Object Access Protocol (SOAP); Web Services Description Language (WSDL); and Universal Description and Discovery Interface (UDDI). The web services audience should be acquainted with BMC ProactiveNet, BMC PATROL, and BMC Impact Manager. The web services audience should have experience in

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

Support overviewYou request the BMC Impact Integration Developer’s 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

http://devcon.bmc.com

http://devcon.bmc.com

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.

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

Atrium service registrationThe BMC II Web Services component is installed separately. See the BMC Impact Integration Web Services Getting Started Guide for instructions about how to install this web services component.

16 BMC Impact Integration Web Services Developer Guide

Registering BMC II Web Services with the BMC UDDI server

Registering BMC II Web Services with the BMC UDDI server

The BMC II Web Services uddi_registry directory contains tools that you can use to access the BMC UDDI server. You can use the UDDI Registry tool to publish, unpublish, and look up the BMC II Web Services. You can invoke the UDDI Registry tool by using the following command line scripts under the uddi_registry/bin directory:

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

To use the command scripts

Before running the scripts, you must first verify the environment variables in the iiws_uddi_env script and edit the iiws_uddi_registry.properties file.

1 Verify the JAVA_HOME and IIWS_HOME environment variables in the bin/iiws_uddi_env script. If the value is not correct, edit the file and set it to the 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:

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


Overview of BMC Impact Integration Web Services

Overview of BMC Impact Integration Web Services

BMC Impact Integration Web Services (BMC II Web Services) supports integrated, workflow-based applications that are required for business service management.

The BMC II Web Services is ported to Axis2/Java.

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

Platform and required tools or components for development

The following items are required tools or components for development:

■ 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

NOTE The BMC II Web Services provides a pre-built web service. The web services developer is responsible for building the client.

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


BMC II Web Services overview

■ Axis2 1.5 WAR file

You'll need to copy this to the tomcat "webapps" directory.

BMC II Web Services overviewThe BMC II Web Services APIs enable you, as a web services developer, to build a platform-independent web services client that exchanges events and data with BMC Impact Manager instances.

The BMC II Web Services uses Apache Axis2 to build the web services. The BMC II Web Services is deployed into an Apache Tomcat 6 Web server.

Figure 1 depicts the interaction between the BMC II Web Services server, the BMC Impact Manager cell or cells, and the third-party client.


BMC II Web Services overview

Figure 1 BMC II Web Services server overview

The BMC II Web Services server package includes the following components:

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


BMC II Web Services access

■ A Tomcat web server that provides the HTTP environment and loads BMC II Web Services.

■ UDDI help tools.

■ Client samples.

BMC II Web Services access

Clients can access BMC II Web Services through the service endpoint:

http://hostname:port/imws/services/ImpactManager

You can view the BMC II Web Services server wsdl file through the following example URLs:

http://hostname:port/imws/services/ImpactManager?wsdl

The default port is 9080.

https://hostname:port/imws/services/ImpactManager?wsdl

The default port is 9443.

Features of the BMC II Web Services server

The BMC II Web Services server provides operations for a web service client to exchange events and data with BMC Impact Manager cells. Features of BMC II Web Services server include

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


Features of the BMC II Web Services server

Table 1 lists the names and descriptions for the BMC II Web Services API.

Table 1 BMC II Web Services server API

Operations Descriptions

Send events

Connect Requests BMC II Web Services to connect with specific instances in the BMC Impact Manager network.

Disconnect Requests BMC II Web Services to disconnect from a connected instance.

SendEvent Sends an event to a connected BMC Impact Manager cell.

Query data, events, and service model

EndQuery Requests to end the query.

GetQueryResultCount Gets the total number of events or data objects that the BMC II Web Services server has retrieved in response to a query.

QueryClassDefinitions Retrieves the class and slot definitions of a specific base class and its subclasses.

QueryData Connects to a specific BMC Impact Manager cell and queries for data.

QueryComponent Connects to a specific BMC Impact Manager cell and retrieves the component data attributes.

QueryComponentsByCondition Connects to a specific BMC Impact Manager cell and queries for components by a specific condition.

QueryComponentsByStatus Connects to a specific BMC Impact Manager cell and queries for components by a specific status.

QueryComponentEvents Connects to a specific BMC Impact Manager cell and retrieves events associated with a component object.

QueryComponentStatus Connects to a specific BMC Impact Manager cell and queries for the status of specific components.

QueryEvents Connects to a specific BMC Impact Manager cell and queries for events.

QueryEventsByDate Connects to a specific BMC Impact Manager cell and queries for events that occurred within a specific date range.

QueryEventByID Connects to a specific BMC Impact Manager cell and queries for specific events by ID.

QueryModelImpact Retrieves possible consumer components of a specified component.

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


Components of the BMC II Web Services server


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

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.

RetrieveQueryResults Retrieves the results that are returned for a query.

UnregisterStateChange Remove integration with a cell, which stops the receipt of state change events.

Subscribe events

AckEvents Directs the web service client to notify the BMC II Web Services server that it has received the events.

GetEvents Enables the web service client to poll events from the BMC II Web Services server gateway.

Subscribe Allows the web service client to specify which event types it wants to receive. It opens the gateway server in BMC II Web Services server to receive events from the cell.

Unsubscribe Enables the web service client to stop its subscription to specified events.

Miscellaneous

GetCellInfo Obtains information about the BMC Impact Manager cells from the BMC II Web Services server.

GetFilterNames Retrieves the names of the available selectors to which the client can subscribe.

RegisterStateChange Registers integration with a cell, which enables receipt of state change events.

SetMaintenanceMode Sends a request to place a specified component in maintenance mode.

SetManualStatus Sends a request to set a designated manual status on the specified component.

cell local mc localhost:1828cell IIWSGatewayserver mc 127.0.0.1:1859

Table 1 BMC II Web Services server API




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.

BMC II Web Services 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. It is accessed at runtime by BMC II Web Services.

The ImWebServices.conf file contains parameters for MessageBuffer, event persistency, and parameters specific to BMC II Web Services.

BMC II Web Services selector file

The BMC II Web Services uses the selector file to define groups of criteria (called

selectors) that are used to identify and select events that propagate from BMC

Impact Manager cells. The default selector file iiws.selector is stored in the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory.


C h a p t e r 2
2 Securing web services
This chapter presents information on how to secure web services. It is addressed to developers or security administrators who are knowledgeable about the WS-Security standards and secure sockets layer (SSL) implementations.

Securing BMC II Web ServicesBMC II Web Services support Transport-level security, the SSL security. By default, Apache Tomcat 6 is configured to support both HTTP and HTTPS connections for one-way server SSL authentication. The HTTPS SSL protocol is TLS.

After installation, clients are able to connect to the BMC II Web Services through both HTTP and HTTPS connectors. If a customer wants to restrict the connection to only HTTPS, he must modify the Tomcat server configuration to set the connectors. For information about how to limit the HTTP connector, see “Modify the security configuration” on page 26.

Default keystore files

BMC II Web Services provide a set of keystore files for HTTPS connection. The keystore files are in the following directory:

$IIWS_HOME/Tomcat/webapps/imws/WEB-INF/


Modify the security configuration

Table 2, Table 3, and Table 4 provide the details of those default keystore files.


You can modify the security configuration so that BMC II Web Services is accessible only through HTTPS, and you can modify the keystore file.

Table 2 Details for the iiwsssl.jks keystore file

Keystore Description

FileName $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/security/iiwsssl.jks

Default keystore for BMC II Web Services used in HTTPS connector.

Type Java KeyStore (jks)

Alias name iiwsssl

Keystore Password

bmciiws

Key Password bmciiws

Table 3 Details for the iiwscacerts.jks keystore file


FileName $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/security/iiwscacerts.jks

This keystore contains the public keys for common trusted certificate authorities. Customer can import this file into the client side and use it as the tustStore.

Type Java KeyStore (jks)

Password bmciiws

Table 4 Details for the iiwsssl.cer keystore file


FileName $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/security/iiwsssl.cer

This file is a public x509 certificate for the iiwsssl key pair. If you already have your own certificate file, you can import the iiwsssl.cer file into your current certificate file so that your current certificate is trusted.

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.



Setting the HTTPS-only connector element

By default, Tomcat enables both HTTP and HTTPS connections. You can, however, configure security settings so that the BMC II Web Services is accessible only through HTTPS.

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

The connector element looks similar to the following example:

3 Comment out the connector element by enclosing it in comment signs, as in the following example:

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

Changing the keystore file

BMC II Web Services uses the default keystore file. However, you can replace the default keystore file with a keystore file that you want to use.

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:

<Connector port="9080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="9443" />

<!-<Connector port="9080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="9443" />-->



Define a SSL HTTP/1.1 Connector

The connector element looks similar to the following example:

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.

Configuring a web service client to support SSL/HTTPS

To support SSL/HTTPS communication for your web service client, you must consider the

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

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:

■ Use the web service tool to import the Java Key Store files from the BMC II Web servers server web services URL.

<Connector port="9443" protocol="org.apache.coyote.http11.Http11Protocol" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" maxThreads="200" acceptCount="100" minSpareThreads="5" maxSpareThreads="75" enableLookups="true" disableUploadTimeout="true" keystoreFile="C:\Program Files\BMC Software\Impact Web Services\Tomcat\webapps\imws\WEB-INF\security\iiwsssl.jks" keystorePass="bmciiws" />

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.



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

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

:"java -Djavax.net.ssl.trustStore=C:\IIWS_client\security\iiwscacerts.jks - Djavax.net.sll.trustStorePassword=bmciiws"


C h a p t e r 3
3 Guidelines for choosing client interfaces
This chapter describes guidelines for choosing a web services client interface that is compatible with the BMC II Web Services server. BMC neither supports nor endorses a particular client interface.

Client componentsWhen you build a client interface, you use these components:

■ the client source code that you generate using the WSDL code generator ■ the customized client code that you write

Programming language

You can use any programming language that is supported by web services and your toolkit of choice.


Guidelines for building a client interface

Guidelines for building a client interfaceThis section describes the steps that you must perform to build a web services client that is compatible with the server.

1. Determine the type of client that you want to create:

2. Chose the appropriate framework (toolkit) for constructing your web services client.

3. Use the WSDL source-code generator from your toolkit to generate the client proxy (client stub) from the WSDL.

4. Use the generated client proxy code as a basis and decide which functions to use in your client code.

5. Write the custom code for the selected client features.

6. Test the client.

Generating the client proxy code (client stubs)

To write the web service client, you first need to generate the client stub out of the web service WSDL by using the tool from the framework you selected. You can generate the client stubs against the web service WSDL through the URL or against the copy of the local web service WSDL file.

The following is an example of how you can generate the client stub by using the Axis2 wsdl2java tool:

"%AXIS2_HOME%\bin\wsdl2java.bat" -o iiwsClient -s -sp -p IIWS_Client_stub -S runtime -uri http://localhost:9080/imws/services/ImpactManager?wsdl


Summary of BMC II Web Services operations

Summary of BMC II Web Services operationsBMC II Web Services server provides operations for a web service client to exchange events and data with BMC Impact Manager cells. BMC II Web Services server performs the following operations:

■ 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 BMC II Web Services server API (part 1 of 2)


Send events

Connect Requests BMC II Web Services to connect with specific instances in the BMC Impact Manager network.

Disconnect Requests BMC II Web Services to disconnect from a connected instance.

SendEvent Sends an event to a connected BMC Impact Manager cell.

Query data, events, and service model

EndQuery Requests to end the query.

GetQueryResultCount Gets the total number of events or data objects that the BMC II Web Services server has retrieved in response to a query.

QueryClassDefinitions Retrieves the class and slot definitions of a specific base class and its subclasses.

QueryData Connects to a specific BMC Impact Manager cell and queries for data.

QueryComponent Connects to a specific BMC Impact Manager cell and retrieves the component data attributes.

QueryComponentsByCondition Connects to a specific BMC Impact Manager cell and queries for components by a specific condition.

QueryComponentsByStatus Connects to a specific BMC Impact Manager cell and queries for components by a specific status.


Summary of BMC II Web Services operations

QueryComponentEvents Connects to a specific BMC Impact Manager cell and retrieves events associated with a component object.

QueryComponentStatus Connects to a specific BMC Impact Manager cell and queries for the status of specific components.

QueryEvents Connects to a specific BMC Impact Manager cell and queries for events.

QueryEventsByDate Connects to a specific BMC Impact Manager cell and queries for events that occurred within a specific date range.

QueryEventByID Connects to a specific BMC Impact Manager cell and queries for specific events by ID.

QueryModelImpact Retrieves possible consumer components of a specified component.

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

RetrieveQueryResults Retrieves the results that are returned for a query.

UnregisterStateChange Remove integration with a cell, which stops the receipt of state change events.

Subscribe events

AckEvents Directs the web service client to notify the BMC II Web Services server that it has received the events.

GetEvents Enables the web service client to poll events from the BMC II Web Services server gateway.

Subscribe Allows the web service client to specify which event types it wants to receive. It opens the gateway server in BMC II Web Services server to receive events from the cell.

Unsubscribe Enables the web service client to stop its subscription to specified events.

Miscellaneous

GetCellInfo Obtains information about the BMC Impact Manager cells from the BMC II Web Services server.

GetFilterNames Retrieves the names of the available selectors to which the client can subscribe.

RegisterStateChange Registers integration with a cell, which enables receipt of state change events.

SetMaintenanceMode Sends a request to place a specified component in maintenance mode.

SetManualStatus Sends a request to set a designated manual status on the specified component.

Table 5 BMC II Web Services server API (part 2 of 2)



BMC II Web Services client sample code

BMC II Web Services client sample code

BMC II Web Services provides a complete set of client sample programs that help integration developers to build the BMC II Web Services client. The sample programs are located under $IIWS_HOME/Tomcat/webapps/imws/client_samples. Sample programs are developed on the Axis2 java framework.

To demonstrate the APIs, the BMC II Web Services provides mc_iiws.baroc file for client samples. The baroc file defines an IIWS_TEST_EV event and an IIWS_TEST_DATA data classes used in the BMC II Web Services client sample programs. To run the client sample, copy the baroc file to the cell’s KB directory, load and compile (mccomp), and restart the cell.

Implementing the BMC II Web Services operations

The rest of this chapter provides you with information on how to implement the BMC II Web Services client for

Implementing send events

You can create an BMC II Web Services client to send events from event source to the BMC Impact Manager cell. The client integration is responsible for designing and implementing the logic required to get the event from the event source, transfer it to BMC II Web Services event and send events to BMC II Web Services.

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



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.

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:

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

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.



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.

To build your queries, invoke the following key operations in sequence:

1. One of the queries listed in Table 5 on page 33.

Invoke the specific query operation first. In the specific query, you identify what you are querying for and specify the BMC Impact Manager instance to which you are connecting. A query result handle is returned that is used to track all related queries in this sequence.

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.

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.



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.

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.

Implementing query class definitions

Unlike other query information which needs the block of query, retrieve, and end query, the query class definitions API enrapture all three processes in a single API: queryClassDefinitions.

By using queryClassDefinitions, you can specify if you want to have data class def and event class def. You can retrieve a single class definition, or you can request to retrieve all the children classes from the base class you provided.

Client samples

You can find the query class definition sample in the %IIWS_HOME%\Tomcat\webapps\imws\client_samples\testDataQueries directory.

TIP The client must call the EndQuery operation to perform the following tasks:

■ 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



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.

Implementing subscribe events

You can build a client interface that receives events propagated from a BMC Impact Manager cell.

Table 6 on page 39 describes the essential components for a client interface that receives events.

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:

■ Always matches■ Modifies■ EveryThing

Table 6 Components that support a receive interface

Component Description

IIWSGatewayserver The IIWSGatewayserver is a listen server. If there is client subscribe request, The IIWSGatewayserver will open a listen socket and accept events propagated from Impact manager cell

Propagate rules or event propagation policies

To receive events from BMC Impact Manager instances, you must define Propagate rules or event propagation policies in the cell for the event types to be sent. The BMC Impact Manager instance sends events to the IIWSGatewayserver based on the rules or polices that you have defined.

Note: You do not need to define Propagate rules or event propagation policies to receive service component state change events only.

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.



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.

Reliable and non-reliable subscriptions

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.

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.

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.



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.

NOTE The callbackURL input parameter is not used in the Subscribe API in BMC II Web Services 7.4.



Other Implementation consideration

Client binding timeout

Integration client may get time out exception if the request call to web services is in progress while timeout occurred in either socket level or in web services framework level. It is the responsibility of integration application to set the adequate binding timeout for the BMC II Web Services client. It is recommended that clients set the configurable binding-timeout properties to allow end user to adjust the value for their running environment.

The way set the binding timeout in client code is various depends on the language and framework client integration use. You can find the code example in the BMC II Web Services client sample code for Axis2 java program.

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.


C h a p t e r 4
4 BMC Impact Integration Web Services server Administration
This chapter describes configuration files that affect how the underlying BMC 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Selector file overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44How the BMC II Web Services server reads selector files and parameters. . . . . . . . . 44Selector file description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Editing the selector file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Configuration file parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Editing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

mcell.dir file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62


Starting server instances

Starting server instancesThe web services server administrator is responsible for starting and maintaining the server.

Selector file overviewThe BMC II Web Services APIs use the selector file to define groups of criteria (called selectors) that are used to identify and select messages which propagate from BMC Impact Manager instances. Messages that match all the criteria in a selector become available to the subscribe-polling mechanisms of BMC II Web Services.

The selector file is a case-insensitive text file. The selector file is required for BMC Impact Integration Web Services’ clients that receive events from BMC Impact Manager instances.

A default selector file, iiws.selector, is stored under the 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:

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.

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

svci:IIAPISelectorFile="C:\Program Files\BMC Software\ImpactIntegration Web Services/mcell/iiws.selector"


Selector file description

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.

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

Selector file descriptionThe following topics describe the structure and content of message selector set files.

NOTE Whenever a client subscribes to multiple selectors, it runs the risk of receiving duplicate messages from a cell. The same message can satisfy the different criteria specified by each selector name and be forwarded to the subscribing client.

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


Characteristics

Characteristics

Message selector set files have the following characteristics:

■ Message selector set file criteria are not case sensitive.

■ The naming convention for message selector set files is integrationName.selector.

■ Message selector set file syntax is checked when the message selector set file is loaded. If the message selector set file contains problematic syntax, the BMC II 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.


Characteristics

■ Each line in a message selector contains only one message selector criterion.

■ The message selector file supports the following comparison operators

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

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

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

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

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

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

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

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


Format

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

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

Message selector set header

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

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


Format

Message selector header

A message selector header

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

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

selector groups included within it, are enabled for use

Table 7 Message selector set header contents

Parameter Description Inclusion

SelectorSetName= name of the message selector set

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

Required

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

Optional

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

Optional

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

Optional

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

Optional

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

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required

Figure 3 Sample message selector set header

SelectorSetName=testselectorFormatVersion=2Version=7.1ChangeDate=November 14, 2007Description=This file contains the event selector testsEnable=TRUE


Format

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

Table 8 describes the required and optional message selector header parameters that precede each message selector.

Table 8 Message selector header contents

Parameter Description Inclusion

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

The name must be unique within the message selector set.

Required

Description= free-text description of the message selector Optional

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

Valid values:

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

■ FALSE – missing slots cause the line to be ignored

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

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

Optional

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

Optional

Enable= specifies whether the message selector is enabled for use

Valid values:

■ TRUE – enabled■ FALSE – disabled

Required


Format

Message selector criteria

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

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

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

Format issues

Messages selector functions, which are internal to the message selector file, are described in Table 9 on page 52. Operators are described in Table 10 on page 55.

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

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

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

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

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

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

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

Figure 4 Sample message selector set header

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


Format

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

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

$ClassName = "SECURITY_ALERT"

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

Table 9 Message selector functions (part 1 of 4)

Function Description

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

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

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

Examples:

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

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

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

Example: slot.severity = “Critical”


Format

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

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

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

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

Example of $doselector calling a subselector:

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

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

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

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

Example: $SlotPresent(slot.severity)

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




Format

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

Example: $SlotPresent(slot.severity)

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

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

Examples:

mc_date=$TimeTSlot.mc_date=$TimeT

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

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

Examples:

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

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

Examples:

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

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

Examples:

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

$subString extracts specified components of a string

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

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

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

Example: mc_host=$ToLower(slot.hostname)

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

Example: mc_domain=$ToUpper(slot.domain)




Format

Table 10 describes the operators used for comparison in a message selector set file.

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

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

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

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

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

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

Example: mc_host=$HostFromIp(slot.srcIP)

Table 10 Message selector operators (part 1 of 3)

Operators Description

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

Example: $Slot.Test = “EVENTS”

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

Example: $ClassName!="EVENT"

=~ regular expression operator

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

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

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

!=~ 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~."




Format

||OR

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

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

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

&&AND

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

Example: AND relationship between message selector groups

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

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

{ } 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”}

}




Format

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.

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

Example: slot.Test>10

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

Example: slot.Test>=11

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

Example: slot.Test<12

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

Example: slot.Text<=11

Table 11 Keyword descriptions

Keyword Description

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

Example: metaslot.class_name="EVENT"

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

Example: reqdslot.msg="TEST"

slot. designates a readable slot value in regular expressions

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

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

NOTE For additional information about selector files, see the BMC Impact Integration Developer’s Kit C API Developer Guide.




Editing the selector file

Editing the selector file

1 If necessary, copy the iiws.selector file from the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory to the working directory of your BMC II Web Services server installation.

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

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

4 Save the file using the file name of your choice and the file extension .selector. If you change the name of the selector file, modify the server instance parameter svci:IIAPISelectorFile in the 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 fileThe 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.

Configuration file parameters

Table 12 on page 59 lists and describes the configuration file parameters.

The default ImWebServices.conf file contains a subset of these values, plus unique configuration parameter values.



Table 12 Configuration file parameters (part 1 of 3)

Group Parameters Description

Message Buffer

MessageBufferKeepSent The number of seconds to keep sent messages buffered while waiting for an answer.

Default: 300 seconds

MessageBufferKeepWait The number of seconds that messages are retained in the buffer while waiting for the connection to be established

Default: 3600 seconds (one hour)

MessageBufferBaseSize The number of messages that can be stored in the message buffer.

Default: 5000 messages

MessageBufferSizeLimit The maximum number of messages that can be stored in the message buffer.

Default: 0

MessageBufferReconnectInterval (Optional) The number of seconds between attempts to connect to a BMC Impact Manager cell.

Default: 120

Notes:

■ 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 The number of times to resend unanswered messages.

Default: 1

MessageBufferExpandPercentage

The percentage that the message buffer can expand.

Default: 10



Event Persistency

PersistencyEnabled Enables persistency, which specifies additional buffering parameters when the buffer mode is No.

Valid values:■ No (Default)■ Yes

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

Valid values:■ None (Default)■ Low ■ High

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

PersistencyFileName The name of the file where the buffered messages are stored.

Default: log/imgw-mposter.dat

PersistencyCleanupSizeThreshold

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

Default: 100000

PersistencyCleanupGarbageThreshold

The threshold percentage of the persistency file that activates garbage collection.

Default: 40 percent.

PersistencyDisconnectRemoveMessages

Indicates whether messages written to the persistency file are deleted when the integration is intentionally disconnected from a BMC Impact Manager cell.

Valid values:■ No ■ Yes (Default value)

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

PersistencyCleanupRefuseFile Default: Yes

PersistencyStatisticsLevel Default: None




Editing the configuration file

Editing the configuration file

1 Using a text editor, open the ImWebServices.conf file.

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.

5 Restart the BMC II Web Services server.

Impact Manager Web services

GateWayserverName The gateway server for the BMC II Web Services server that, like a listener server, receives messages from the cell. The GateWayserverName parameter value and the name in the mcell.dir file of the BMC II Web Services must be the same.

Default: IIWSGatewayserver

MaxReturnEventListSize The maximum size of the event or data returned each time in response to RetrieveQueryResults or GetEvents.

Default: 20

MaxSubscriberNumber The maximum number of subscrptions allowed for the gateway server.

Default: 100

RecvBufferSize The maximum number of matching events stored in gateway persistent receiver buffer. If the number of events received exceed the RecvBufferSize, old events are removed from the persistent receiver buffer.

Default: 2000

SelectorFileName The file that defines the filter criteria used to identify and select the events that are propagated from Impact Managers.

Default: iiws.selector

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




mcell.dir file

mcell.dir fileThe 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.


A p p e n d i x A
A BMC Impact Integration Web Services Data Types
This Appendix describes both the namespace definitions and the data types of the ImpactManager.wsdl.

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

Imported schema definitionsThe ImpactManager.wsdl incorporates its own data type and element declarations and the data type definitions of four imported schema definition documents: Event.xsd BasicTypes.xsd, ImapiTypes.xsd, and ImapiElems.xsd.

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.


Elements

ElementsTable 13 describes the elements that the <wsdl:types> section exposes. These elements are derived from built-in, simple, and complex data types.

Table 13 Elements (part 1 of 2)

Element Built-in Data Type Simple Type Complex Type

baseClass string — —

bufferType — IMBufferType —

CellInfo_Array — — ArrayOf_CellInfo

ClassDefInfo_Array — — ArrayOf_ClassDefInfo

ClassDefInfo_element — — ClassDefInfo

className string — —

classNames string — —

classOnly boolean — —

comment string — —

componentCauseId string — —

componentId string — —

componentStatus string — —

componentStatusId string — —

condition string — —

connection long — —

connectionId long — —

context string — —

context_nio string — —

deleteBuffer boolean — —

endDate string — —

errorCode int — —

eventID string — —

filterName string — —

GetEventsResponse_element

— — GetEventsResponse

GetQueryResultResponse_element

— — GetQueryResultResponse

getSubclasses boolean — —

imFailure string — —

imname string — —

long_Response long — —

message — — Event

messageClass string — —


Elements

messageID string — —

messageType — IMMessageType —

modeToSet string — —

num_of_components int — —

num_of_events int — —

num_of_results int — —

onlyImpacted boolean — —

password string — —

query string — —

QueryMode_element — — QueryMode

query_ev string — —

regID string — —

reliable boolean — —

resultCode int — —

resultHandle string — —

retrieveResultHandle string — —

securityToken string — —

serverName string — —

setOrCleared boolean — —

SlotDefInfo_Array — — ArrayOf_SlotDefInfo

SlotDefInfo_element — — SlotDefInfo

slotsList string — —

SMComponent_element — — SMComponent

SMComponentArray_element

— — ArrayOf_SMComponent

startDate string — —

startIndex long — —

StateChangeType_element

— — StateChangeType

timeout int — —

trueCause boolean — —

userName string — —

Table 13 Elements (part 2 of 2)

Element Built-in Data Type Simple Type Complex Type


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.

bufferType

The element declaration for the element bufferType is shown below.

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.

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.

<xsd:element name=”baseClass” nillable=”true” type=”xsd:string”/>

<xsd:element name=”bufferType” nillable=”true” type=”tns:IMBufferType”/>

<xsd:element name=”CellInfo_Array” type=”tns:ArrayOf_CellInfo”/>


ClassDefInfo_Array

ClassDefInfo_Array

The element declaration for the element ClassDefInfo_Array is shown below.

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.

This element references the complex type ClassDefInfo, described on page 97.

className

The element declaration for className is shown below.

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=”ClassDefInfo_Array”type=”tns:ArrayOf_ClassDefInfo”/>

<xsd:element name=”ClassDefInfo_element” type=”tns:ClassDefInfo”/>

<xsd:element name=”className” nillable=”true” type=”xsd:string”/>

<xsd:element name=”classNames” nillable=”true” type=”xsd:string”/>


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.

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.

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=”classOnly” type=”xsd:boolean”/>

<xsd:element name=”comment” nillable=”true” type=”xsd:string”/>

<xsd:element name=”componentCauseId” nillable=”true” type=”xsd:string”/>


componentId

componentId

The declaration for the element componentId is shown below.

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.

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.

condition

The element declaration for the element condition is shown below.

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.

<xsd:element name=”componentId” nillable=”true” type=”xsd:string”/>

<xsd:element name=”componentStatus” nillable=”true” type=”xsd:string”/>

<xsd:element name=”componentStatusId” nillable=”true” type=”xsd:string”/>

<xsd:element name=”condition” nillable=”true” type=”xsd:string”/>


connection

connection

The <wsdl:types> section contains the element declaration for the element connection.

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:

■ Disconnect_Request■ SendEvent_Request

connectionId

The <wsdl:types> section contains the element declaration for the element connectionId.

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 built-in type long. The connectionId element is part of the following messages:

■ Connect_Request■ Connect_Response

context

The <wsdl:types> section contains the element declaration for the element context.

<xsd:element name=”connection” type=”xsd:long”/>

<xsd:element name=”connectionId” type=”xsd:long”/>

<xsd:element name=”context” nillable=”true” type=”xsd:string”/>


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:

■ Subscribe_Request■ Unsubscribe_Request

context_nio

The declaration for the element context_nio is shown below.

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.

The Cstatus_element references the complex type CStatus, which is described on page 100.

cStatusHigh

The declaration for the element cStatusHigh is shown below.

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.

<xsd:element name=”context_ack” nillable=”true” type=”xsd:string”/>

<xsd:element name=”Cstatus_element”type=”tns:CStatus”/>

<xsd:element name=”cStatusHigh” nillable=”true” type=”xsd:string”/>


cStatusLow

cStatusLow

The declaration for the element cStatusLow is shown below.

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.

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.

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.

<xsd:element name=”cStatusLow” nillable=”true” type=”xsd:string”/>

<xsd:element name=”deleteBuffer” type=”xsd:boolean”/>

<xsd:element name=”endDate” nillable=”true” type=”xsd:dateTime”/>


errorCode

errorCode

The declaration for the element errorCode is shown below.

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.

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.

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 built-in type string. It is valid even when it carries no content. The filterName element is part of the following messages:

■ Subscribe_Request■ Unsubscribe_Request

<xsd:element name=”errorCode” nillable=”true” type=”xsd:int”/>

<xsd:element name=”eventID” nillable=”true” type=”xsd:string”/>

<xsd:element name=”filterName” nillable=”true” type=”xsd:string”/>




The declaration for the element GetEventsResponse_element is shown below.

The GetEventsResponse_element references the complex type GetEventsResponse, described on page 100.

GetQueryResultResponse_element

The declaration for the element GetQueryResultResponse_element is shown below.

The GetQueryResultResponse element references the complex type GetQueryResultResponse, described on page 100.

getSubclasses

The declaration for the Boolean element getSubclasses is shown below.

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.

The element imFailure is used in fault messages as the parameter that contains the fault error.

<xsd:element name=”GetEventsResponse_element” nillable=”true” type=”tns:GetEventsResponse”/>

<xsd:element name=”GetQueryResultResponse_element” nillable=”true” type=”tns:GetQueryResultResponse”/>

<xsd:element name=”getSubclasses”type=”xsd:boolean”/>

<xsd:element name=”imFailure” nillable=”true” type=”xsd:string”/>


imName

imName

The <wsdl:types> section contains the element declaration for the element imName.

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.

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.

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.

<xsd:element name=”imName” nillable=”true” type=”xsd:string”/>

<xsd:element name=”long_Response” type=”xsd:long”/>

<xsd:element name=”message” nillable=”true” type=”event:Event”/>


messageClass

messageClass

The <wsdl:types> section contains the element declaration for the element messageClass.

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.

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.

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.

<xsd:element name=”messageClass” type=”xsd:string”/>

<xsd:element name=”messageID” nillable=”true” type=”xsd:string”/>

<xsd:element name=”messageType” nillable=”true” type=”tns:IMMessageType”/>


modeToSet

modeToSet

The declaration for the element modeToSet is shown below.

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.

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.

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.

<xsd:element name=”modeToSet” nillable=”true” type=”xsd:string”/>

<xsd:element name=”num_of_components” type=”xsd:int”/>

<xsd:element name=”num_of_events” type=”xsd:int”/>


num_of_results

num_of_results

The declaration for the element num_of_results is shown below.

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.

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.

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.

<xsd:element name=”num_of_results” type=”xsd:int”/>

<xsd:element name=”onlyImpacted” type=”xsd:boolean”/>

<xsd:element name=”password” nillable=”true” type=”xsd:string”/>


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.

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.

The QueryMode_element references the simple type QueryMode, described on page 88.

regID

The declaration for the element regID is shown below.

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.

<xsd:element name=”query” nillable=”true” type=”xsd:string”/>

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.

<xsd:element name=”QueryMode_element” type=”tns:QueryMode”/>

<xsd:element name=”regID” nillable=”true” type=”xsd:string”/>


reliable

reliable

The declaration for the element reliable is shown below.

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.

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.

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:

■ GetQueryResultCount_Request■ EndQuery_Request

<xsd:element name=”reliable” type=”xsd:boolean”/>

<xsd:element name=”resultCode” type=”xsd:int”/>

<xsd:element name=”resultHandle” nillable=”true” type=”xsd:string”/>


retrieveResultHandle


The declaration for the element retrieveResultHandle is shown below.

Used in query requests, the retrieveResultHandle element contains a string type that contains the ID returned by the server’s 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.

The securityToken element is a placeholder for future security implementations.

serverName

The declaration for the element serverName is shown below.

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.

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.

<xsd:element name=”retrieveResultHandle” nillable=”true” type=”xsd:string”/>

<xsd:element name=”securityToken” nillable=”true” type=”xsd:string”/>

<xsd:element name=”serverName” nillable=”true” type=”xsd:string”/>


setOrCleared

setOrCleared

The declaration for the element setOrCleared is shown below.

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.

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.

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=”setOrCleared” type=”xsd:boolean”/>

<xsd:element name=”SlotDefInfo_Array”type=”tns:ArrayOf_SlotDefInfo”/>

<xsd:element name=”SlotDefInfo_element”type=”tns:SlotDefInfo”/>

<xsd:element name=”slotsList” nillable=”true” type=”xsd:string”/>


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.

The SMComponent_element references the complex type SMComponent, described on page 98.

SMComponentArray_element

The declaration for the element SMComponentArray_element is shown below.

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.

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.

<xsd:element name=”SMComponent_element” type=”tns:SMComponent”/>

<xsd:element name=”SMComponentArray_element”type=”tns:ArrayOf_SMComponent”/>

<xsd:element name=”startDate” nillable=”true” type=”xsd:dateTime”/>


startIndex

startIndex

The <wsdl:types> section contains the element declaration for the element startIndex.

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.

StateChangeType_element

The declaration for the element StateChangeType_element is shown below.

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.

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 buffer—if one is defined for the BMC Impact Manager instance—and the SendEvent operation exits.

<xsd:element name=”startIndex” type=”xsd:long”/>

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.

<xsd:element name=”StateChangeType_element”type=”tns:StateChangeType”/>

<xsd:element name=”timeout” type=”xsd:int”/>


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.

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 component’s status.

userName

The <wsdl:types> section contains the element declaration for the element userName.

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 TypesTable 14 on page 85 lists the custom simple types that the ImpactManager.wsdl exposes and their corresponding built-in data types.

<xsd:element name=”trueCause” type=”xsd:boolean”/>

<xsd:element name=”userName” nillable=”true” type=”xsd:string”/>

Table 14 Simple Types

Simple Type Built-in Data Type

IMMessageType string

IMBufferType string

DataType string

QueryMode string


IMMessageType

IMMessageType

The <wsdl:types> section contains the data definition for IMMessageType simple type.

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.

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

Value Description

MSG_TYPE_NONE empty message

MSG_TYPE_NEW_EVENT message contains a new event object

MSG_TYPE_MOD_EVENT message contains information for modifying an existing event object

MSG_TYPE_NEW_DATA message contains a new data object

MSG_TYPE_OVERWRITE_DATA message contains information for modifying an existing data object. If the data object does not already exist, then this operation creates it.

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


IMBufferType

IMBufferType

The <wsdl:types> section contains the data definition for the simple type IMBufferType.

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.

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

Value Description

BMCII_BUFFER_MODE_DEFAULT

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.

BMCII_BUFFER_MODE_LOW

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.


DataType

DataType

The schema declaration file Basic Types.xsd contains the data definition of the simple type DataType.

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.

NOTE The buffer resides on the C API interface with the BMC Impact Manager network.

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


Complex Types

QueryMode defines which set of class definitions and respective subclasses are being queried: BMCII_EVENT_CLASSES or BMCII_DATA_CLASSES.

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

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

Table 15 Complex Types (part 1 of 2)

Derived Element Complex Type Child Element Data Type (Child Element)

ByteArray ArrayOf_Byte byte_element byte

ShortArray ArrayOf_Short short_element short

IntArray ArrayOf_Int int_element int

LongArray ArrayOf_Long long_element long

FloatArray ArrayOf_Float float_element float

DoubleArray ArrayOf_Double double_element double

StringArray ArrayOf_String string_element string


Arrays from Built-In Data Types


The Basic Types.xsd schema file defines the following arrays. Each array is a complex type with standard content.

value_element value byte_value byte

short_value short

int_value int

long_value long

float_value float

double_value double

string_value string

ShortArray —

IntArray —

LongArray —

FloatArray —

DoubleArray —

StringArray —

NameValue_element NameValue name string

value value

value_type DataType

NameValueArray_element

ArrayOf_NameValue NameValue_element NameValue

NameValueTable_element

TableOf_NameValue NameValueArray_element

ArrayOf_NameValue

Event_element Event (extending ArrayOf_NameValue)

subject string

EventArray_element ArrayOf_Event Event_element Event

— Cell_Info cell_name string

cell_type string

cell_hostname string

port unsigned int

encryption_key string

trusted_servers string

— ArrayOf_CellInfo CellInfo_element CellInfo

— execution_fault IMFailure string

Table 15 Complex Types (part 2 of 2)

Derived Element Complex Type Child Element Data Type (Child Element)



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

ArrayOf_Short

ArrayOf_Int

ArrayOf_Long

NOTE Arrays are similar to the C/C++ structure types (struct). They are user-defined composite types.

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

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

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

<xsd:element name=”LongArray” type=”btypes:ArrayOf_Long”/><xsd:complexType name=”ArrayOf_Long”>


Value Choices, Name-Value Pairs, and Custom Complex Types

ArrayOf_Float

ArrayOf_Double

ArrayOf_String


The remaining complex types define value choices, name-value pairs, and custom types.

<xsd:sequence><xsd:element name=”long_element” minOccurs=”0” maxOccurs=”unbounded” type=”xsd:long”/></xsd:sequence></xsd:complexType>

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

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

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



value

The schema definition file BasicTypes.xsd contains this data definition of value.

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.

The NameValue complex type specifies how a value element is represented. It consists of sequence of child elements:

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

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

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.

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.

Child Element Data Type

name built-in type string

value the complex type value

value_type the simple type DataType

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

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



Event

The schema definition file Event.xsd contains this data definition of the Event complex type.

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.

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.

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

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


Custom complex types in the WSDL


CellInfo

The <wsdl:types> section describes the CellInfo complex type. Its data definition is shown below.

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:

<xsd:complexType name=”CellInfo”>” <xsd:sequence><xsd:element name=”cell_name” type=”xsd:string”/><xsd:element name=”cell_type” type=”xsd:string”/> <xsd:element name=”cell_hostname” type=”xsd:string”/><xsd:element name=”port” type=”xsd:unsignedInt”/><xsd:element name=”encryption_key” type=”xsd:string”/><xsd:element name=”trusted_servers” type=”xsd:string”/></xsd:sequence></xsd:complexType>

Table 16 CellInfo Child Elements (part 1 of 2)

Element Data Type Description

cell_name string string description of the name of the BMC Impact Manager instance or an integration. For an Impact Integration Web Services integration, enter IIWSGatewayserver.

cell_type string string description that identifies the BMC Impact Manager instance as a cell or a gateway. Normally, you enter cell.

cell_hostname string string description that identifies the name of the system on which the instance resides

port unsignedInt numerical designation that specifies the port number through which the BMC Impact Manager instance or integration listens. The default for BMC Impact Manager instances is 1828; the default for IIWSGatewayserver is 1859.



ArrayOf_CellInfo

The <wsdl:types> section describes the ArrayOf_CellInfo complex type. Its data definition is shown below.

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.

encryption_key

string string description of the encryption key that the BMC Impact Manager instance or integration uses. The default value is MC.

trusted_servers

string [not implemented in this release] string description that lists the host names or IP addresses of the authentication servers that are acceptable to the specified BMC Impact Manager instance or integration

<xsd:complexType name=”ArrayOf_CellInfo”>” <xsd:sequence><xsd:element minOccurs=”0” maxOccurs=”unbounded” name=”CellInfo_element” type=”tns:CellInfo”/></xsd:sequence></xsd:complexType>

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

Table 16 CellInfo Child Elements (part 2 of 2)

Element Data Type Description



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.

ArrayOf_ClassDefInfo

The data definition of the complex type ArrayOf_ClassDefInfo is shown below.

The complex type ArrayOf_ClassDefInfo

SMComponent

The data definition of the complex type SMComponent is shown below.

ArrayOf_SMComponent

The data definition of the complex type ArrayOf_SMComponent is shown below.

Element Description

class_parent_idx integer assigned to the selected parent class

class_child_cnt number of child classes

class_name name of the selected class

child_list an array of class definitions of children of the selected parent class

slots_count number of slots in the selected class

slots_list 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 ','.

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

<xsd:complexType name=”SMComponent”><xsd:complexContent><xsd:extension base=”btypes:ArrayOf_NameValue”/></xsd:complexContent></xsd:complexType>



SlotDefInfo

The data definition of the complex type SlotDefInfo is shown below.

This definition uses string types to define the following elements:

<xsd:complexType name=”ArrayOf_SMComponent”><xsd:sequence><xsd:element maxOccurs=”unbounded”minOccurs=”0”name=”SMComponent_element”type=”tns:SMComponent”/></xsd:sequence></xsd:complexType>

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

Element Description

slot_name name of the slot in the selected class

slot_type indicates the type of value that the slot contains. The value can be a single entry or a list-of entry. It can be one of the following types:

■ STRING■ REAL■ POINTER■ INTEGER■ EnumTypeName

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



ArrayOf_SlotDefInfo

The data definition of the complex type ArrayOf_SlotDefInfo is shown below.

CStatus

The data definition of the complex type CStatus is shown below.

GetEventsResponse

The data definition of the complex type GetEventsResponse is shown below.

slot_flags 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

■ r|R = read-only■ k|K = key■ p|P = parse■ d|D = dup_detect■ h|H = hidden

slot_def_value the default value, if any, assigned to the selected slot

<xsd:complexType name=”ArrayOf_SlotDefInfo”><xsd:sequence><xsd:element maxOccurs=”unbounded”minOccurs=”0”name=”SMComponent_element”type=”tns:SlotDefInfo”/></xsd:sequence></xsd:complexType>

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

<xsd:complexType name=”GetEventsResponse”><xsd:sequence>

Element Description



GetQueryResultResponse

The data definition of the complex type GetQueryResultResponse is shown below.

StateChangeType

The data definition of the complex type StateChangeType is shown below.

execution_fault

The data definition of the complex type execution_fault is shown below.

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.

<xsd:element name=”response” type=”event:ArrayOf_Event”/><xsd:element name=”num_of_events” type=”xsd:int”/></xsd:sequence></xsd:complexType>

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

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

<xsd:element name="execution_fault"><xsd:complexType><xsd:sequence><xsd:element name="IMFailure" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType></xsd:element>


Mapping: XSD data types to programming language data types

Mapping: XSD data types to programming language data types

The XSD data types have their equivalent data types in other programming languages, such as C++, Java™, and .NET. Your web services toolkit determines the default mappings of the XSD data types with those of the specific programming language.

For example, the Systinet WASP toolkit for C++ contains default mappings of XSD data types with C++ data types. You can find the runtime mapping information in the serialization.xml file and the mappings for the compiler in the wsdlc.xml. Refer to the Mappings topics in the Systinet documentation for more information.


A p p e n d i x B
B BMC Impact Integration Web Services API operations
This Appendix describes the set of API operations currently defined by the Impact Manager port type. The following topics are described:

PortType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

AckEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107EndQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108GetCellInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109GetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110GetFilterNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112GetQueryResultCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113QueryClassDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115QueryComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117QueryComponentEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118QueryComponentStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120QueryComponentsByCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122QueryComponentsByStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124QueryData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126QueryEventByID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128QueryEvents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129QueryEventsByDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131QueryModelImpact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133QueryModelPossibleRootCauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135RegisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137RetrieveQueryResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139SendEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141SetMaintenanceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142SetManualStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145UnregisterStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148


PortType

PortTypeThe port type Impact Manager groups the operations and the underlying messages of the BMC Impact Integration Web Services.

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

WSDL for AckEvents operation

WSDL messages for AckEvents

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.

<wsdl:operation name="AckEvents" parameterOrder="inargs"><wsdl:input message="tns:AckEvents_Request"/><wsdl:output message="tns:AckEvents_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="AckEvents_Request"> <wsdl:part element="elems:AckEvents" name="inargs"/> </wsdl:message> <wsdl:message name="AckEvents_Response"> <wsdl:part element="elems:NoValue_output" name="outargs"/> </wsdl:message>


Connect

XSD schema for request and response for AckEvents

Parameters for AckEvents

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.

WSDL for Connect operation

<xsd:element name="AckEvents"><xsd:complexType><xsd:sequence><xsd:element name="filterName" nillable="true" type="xsd:string" /><xsd:element name="context_nio" nillable="true" type="xsd:string" /><xsd:element name="num_of_events" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element>

Name Direction Element Name Description

filterName In tns:filterName string type that identifies the name of the event filter that the client has selected. The client is requesting to subscribe to the events that match the criteria specified by the event filter.

context In tns:context string type that identifies the name of the Web Service client that is making the request

num_of_events In tns:num_of_events As the input argument, this is the integer that specifies the number of events the client seeks to receive per polling call.

NOTE The query operations use their own connection protocol, which is distinct from the Connect operation.

<wsdl:operation name="Connect" parameterOrder="inargs"> <wsdl:input message="tns:Connect_Request"/> <wsdl:output message="tns:Connect_Response"/> <wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/> </wsdl:operation>


Connect

WSDL message for Connect

XSD schema for request and response for Connect

Parameters for Connect

<wsdl:message name="Connect_Request"> <wsdl:part element="elems:Connect" name="inargs"/> </wsdl:message> <wsdl:message name="Connect_Response"> <wsdl:part element="elems:Connect_output" name="outargs"/> </wsdl:message>

<xsd:element name="Connect"><xsd:complexType><xsd:sequence><xsd:element name="userName" nillable="true" type="xsd:string"/><xsd:element name="password" nillable="true" type="xsd:string"/><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="bufferType" nillable="true" type="types:IMBufferType" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="Connect_output"><xsd:complexType><xsd:sequence><xsd:element name="connectionId" type="xsd:long" /></xsd:sequence></xsd:complexType></xsd:element>


userName In tns:userName string type that specifies the user name defined for the instance

password In tns:password not currently used

imname In tns:imname string type that identifies the name of the BMC Impact Manager instance

bufferType In tns:bufferType a string type that indicates one of four values:

■ BMCII_BUFFER_MODE_DEFAULT■ BMCII_BUFFER_MODE_NONE■ BMCII_BUFFER_MODE_LOW■ BMCII_BUFFER_MODE_HIGH

See “IMBufferType” on page 87 for a description of the buffer types.

connectionId Out tnc:connectionId long integer that specifies the connection handle


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.

WSDL for Disconnect operation

WSDL messages for Disconnect

XSD schema for request and response for Disconnect

Parameters for Disconnect

<wsdl:operation name="Disconnect" parameterOrder="inargs"><wsdl:input message="tns:Disconnect_Request"/><wsdl:output message="tns:Disconnect_Response"/> <wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="Disconnect_Request"> <wsdl:part element="elems:Disconnect" name="inargs"/> </wsdl:message><wsdl:message name="Disconnect_Response"> <wsdl:part element="elems:NoValue_output" name="outargs"/> </wsdl:message>

<xsd:element name="Disconnect"><xsd:complexType><xsd:sequence><xsd:element name="connection" type="xsd:long" /><xsd:element name="deleteBuffer" type="xsd:boolean" /></xsd:sequence></xsd:complexType></xsd:element>


connection In tns:connection long integer that specifies the connection handle ID of the initiating connection

deleteBuffer In tns:deleteBuffer a boolean indicator that, when set to true, removes a persistent buffer as a result of the disconnect operation


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.

WSDL for EndQuery operation

WSDL messages for EndQuery

XSD schema for request and response for EndQuery

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.

<wsdl:operation name="EndQuery" parameterOrder="inargs"><wsdl:input message="tns:EndQuery_Request"/><wsdl:output message="tns:EndQuery_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="EndQuery_Request"><wsdl:part element="elems:EndQuery" name="inargs"/></wsdl:message><wsdl:message name="EndQuery_Response"><wsdl:part element="elems:NoValue_output" name="outargs"/></wsdl:message>

<xsd:element name="EndQuery"><xsd:complexType><xsd:sequence><xsd:element name="resultHandle" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>


GetCellInfo

Parameters for EndQuery

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.

WSDL for GetCellInfo operation

WSDL messages for GetCellInfo


resultHandle In tns:resultHandle string type that contains the ID returned by the server’s response to the initial query request. This ID is attached to all query requests in this cycle.

<wsdl:operation name="GetCellInfo" parameterOrder="inargs"><wsdl:input message="tns:GetCellInfo_Request"/><wsdl:output message="tns:GetCellInfo_Response"/> <wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="GetCellInfo_Request"> <wsdl:part element="elems:GetCellInfo" name="inargs"/></wsdl:message><wsdl:message name="GetCellInfo_Response"> <wsdl:part element="elems:GetCellInfo_output" name="outargs"/></wsdl:message>


GetEvents

XSD schema for request and response for GetCellInfo

Parameter for GetCellInfo

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

WSDL for GetEvents operation

<xsd:element name="GetCellInfo"><xsd:complexType><xsd:sequence /></xsd:complexType></xsd:element>

<xsd:element name="GetCellInfo_output"><xsd:complexType><xsd:sequence><xsd:element name="CellInfo_Array" type="types:ArrayOf_CellInfo" /></xsd:sequence></xsd:complexType></xsd:element>


cells Out tns:CellInfo_Array string and unsigned integer elements that specify the

■ 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

<wsdl:operation name="GetEvents" parameterOrder="inargs"><wsdl:input message="tns:GetEvents_Request"/><wsdl:output message="tns:GetEvents_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>


GetEvents

WSDL messages for GetEvents

XSD schema for request and response for GetEvents

Parameters for GetEvents

<wsdl:message name="GetEvents_Request"> <wsdl:part element="elems:GetEvents" name="inargs"/></wsdl:message>

<wsdl:message name="GetEvents_Response"> <wsdl:part element="elems:GetEvents_output" name="outargs"/></wsdl:message>

<xsd:element name="GetEvents"><xsd:complexType><xsd:sequence><xsd:element name="filterName" nillable="true" type="xsd:string" /><xsd:element name="context_nio" nillable="true" type="xsd:string" /><xsd:element name="num_of_events" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="GetEvents_output"><xsd:complexType><xsd:sequence><xsd:element name="getEventsResponse" nillable="true" type="types:GetEventsResponse" /></xsd:sequence></xsd:complexType></xsd:element>


filterName In tns:filterName string type that identifies the name of the event selector that the client has chosen. The client is requesting to subscribe to and get the events that match the criteria specified by the filterName. The value of the filterName should match the filterName value specified in the preceding Subscribe operation.



GetFilterNames

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.

WSDL for GetFilterNames operation

WSDL messages for GetFilterNames

num_of_events In/Out tns:num_of_events 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.

response Out event:EventArray_element

complex type that specifies the name of one or more events that are being returned in response to the Web Service client’s polling call

<wsdl:operation name="GetFilterNames" parameterOrder="inargs"><wsdl:input message="tns:GetFilterNames_Request"/><wsdl:output message="tns:GetFilterNames_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="GetFilterNames_Request"> <wsdl:part element="elems:GetFilterNames" name="inargs"/></wsdl:message><wsdl:message name="GetFilterNames_Response"> <wsdl:part element="elems:GetFilterNames_output" name="outargs"/></wsdl:message>



GetQueryResultCount

XSD schema for request and response for GetFilterNames

Parameter for GetFilterNames

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.

WSDL for GetQueryResultCount operation

<xsd:element name="GetFilterNames"><xsd:complexType><xsd:sequence /></xsd:complexType></xsd:element><xsd:element name="GetFilterNames_output"><xsd:complexType><xsd:sequence><xsd:element name="StringArray" type="btypes:ArrayOf_String" /></xsd:sequence></xsd:complexType></xsd:element>


filterNames Out btypes:StringArray string type that identifies one or more selector names currently available to the BMC II Web Services server and to which the client can subscribe to

<wsdl:operation name="GetQueryResultCount" parameterOrder="inargs"><wsdl:input message="tns:GetQueryResultCount_Request"/><wsdl:output message="tns:GetQueryResultCount_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>


GetQueryResultCount

WSDL messages for GetQueryResultCount

XSD schema for request and response for GetQueryResultCount

Parameters for GetQueryResultCount

<wsdl:message name="GetQueryResultCount_Request"> <wsdl:part element="elems:GetQueryResultCount" name="inargs"/></wsdl:message><wsdl:message name="GetQueryResultCount_Response"> <wsdl:part element="elems:GetQueryResultCount_output" name="outargs"/></wsdl:message>

<xsd:element name="GetQueryResultCount"><xsd:complexType><xsd:sequence><xsd:element name="resultHandle" nillable="true" type="xsd:string" /><xsd:element name="timeout" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="GetQueryResultCount_output"><xsd:complexType><xsd:sequence><xsd:element name="resultCount" type="xsd:long" /></xsd:sequence></xsd:complexType></xsd:element>


resultHandle In tns:resultHandle string type that contains the ID returned by the server’s response to the initial query request. This ID is attached to all query requests in this cycle.

timeout In tns:timeout integer that defines the duration for which the client waits for a response to its query from the BMC II Web Services server. If no response to the query is received, then this query request is terminated.

resultCount Out tns:long_Response string 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


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.

WSDL for QueryClassDefinitions operation

WSDL messages for QueryClassDefinitions

<wsdl:operation name="QueryClassDefinitions" parameterOrder="inargs"><wsdl:input message="tns:QueryClassDefinitions_Request"/><wsdl:output message="tns:QueryClassDefinitions_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryClassDefinitions_Request"> <wsdl:part element="elems:QueryClassDefinitions" name="inargs"/></wsdl:message><wsdl:message name="QueryClassDefinitions_Response"> <wsdl:part element="elems:QueryClassDefinitions_output" name="outargs"/></wsdl:message>



XSD schema for request and response for QueryClassDefinitions

Parameters for QueryClassDefinitions

<xsd:element name="QueryClassDefinitions"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="queryMode" type="types:QueryMode" /><xsd:element name="baseClass" nillable="true" type="xsd:string" /><xsd:element name="className" nillable="true" type="xsd:string" /><xsd:element name="classOnly" type="xsd:boolean" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="QueryClassDefinitions_output"><xsd:complexType><xsd:sequence><xsd:element name="classDefs" type="types:ArrayOf_ClassDefInfo" /></xsd:sequence></xsd:complexType></xsd:element>


imname In tns:imName string type that identifies the name of the BMC Impact Manager instance (cell)

queryMode In tns:queryMode_element

numeric indicator that determines which set of class definitions and respective subclasses are being queried: BMCII_EVENT_CLASSES (0) or BMCII_DATA_CLASSES (1)

baseClass In tns:baseClass string that specifies the base class at which the query starts. If you specify NULL, the query returns the top class specified by the queryMode: CORE_DATA or CORE_EVENT

If you specify a className parameter value, you do not enter a baseClass parameter value.

className In tns:className string that specifies the class name for which you want to retrieve information

If you specify a className parameter, you do not enter a baseClass parameter value.


QueryComponent

QueryComponent

The QueryComponent operation retrieves the component data attributes of a specified component object.

WSDL for QueryComponent operation

WSDL messages for QueryComponent

classOnly In tns:classOnly 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

an array of class definitions

<wsdl:operation name="QueryComponent" parameterOrder="inargs"><wsdl:input message="tns:QueryComponent_Request"/><wsdl:output message="tns:QueryComponent_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryComponent_Request"> <wsdl:part element="elems:QueryComponent" name="inargs"/></wsdl:message><wsdl:message name="QueryComponent_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>



QueryComponentEvents

XSD schema for request and response for QueryComponent

Parameters for QueryComponent


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.

<xsd:element name="QueryComponent"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="componentId" 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>


imname In tns:imName string type that identifies the name of the BMC Impact Manager instance

componentId In tns:componentId string type that contains the universal data ID (mc_udid) of the component object

resultHandle Out resultHandle string type that contains the ID returned by the server’s response to the initial query request. This ID is attached to all query requests in this cycle.

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



WSDL for QueryComponentEvents operation

WSDL messages for QueryComponentEvents

XSD schema for request and response for QueryComponentEvents

<wsdl:operation name="QueryComponentEvents" parameterOrder="inargs"><wsdl:input message="tns:QueryComponentEvents_Request"/><wsdl:output message="tns:QueryComponentEvents_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryComponentEvents_Request"> <wsdl:part element="elems:QueryComponentEvents" name="inargs"/></wsdl:message><wsdl:message name="QueryComponentEvents_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>

<xsd:element name="QueryComponentEvents"><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:element name="onlyImpacted" type="xsd:boolean" /></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>


QueryComponentStatus

Parameters for QueryComponentEvents


The QueryComponentStatus operation retrieves a component’s 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:

■ mc_udid■ status■ self_status■ computed_status■ impact_status■ manual_status

WSDL for QueryComponentStatus operation




onlyImpacted In tns:onlyImpacted Boolean indicator (true/false) that indicates whether you want to retrieve only impact events, events that affect the mode of the component, and not direct events that originate from the component

slotsList In tns:slotsList 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 ','.



<wsdl:operation name="QueryComponentStatus" parameterOrder="inargs"><wsdl:input message="tns:QueryComponentStatus_Request"/><wsdl:output message="tns:QueryComponentStatus_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>



WSDL messages for QueryComponentStatus

XSD schema for request and response for QueryComponentStatus

Parameters for QueryComponentStatus

<wsdl:message name="QueryComponentStatus_Request"> <wsdl:part element="elems:QueryComponentStatus" name="inargs"/></wsdl:message><wsdl:message name="QueryComponentStatus_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>

<xsd:element name="QueryComponentStatus"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="componentId" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>




componentStatusId In tns:componentStatusId string type that contains the universal data ID (mc_udid) of the component object, the status of which you are requesting




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.

WSDL for QueryComponentsByCondition operation

WSDL message for QueryComponentsByCondition

<wsdl:operation name="QueryComponentsByCondition" parameterOrder="inargs"><wsdl:input message="tns:QueryComponentsByCondition_Request"/><wsdl:output message="tns:QueryComponentsByCondition_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryComponentsByCondition_Request"> <wsdl:part element="elems:QueryComponentsByCondition" name="inargs"/></wsdl:message><wsdl:message name="QueryComponentsByCondition_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>



XSD schema for request and response for QueryComponentsByCondition

Parameters for QueryComponentsByCondition

<xsd:element name="QueryComponentsByCondition"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="condition" nillable="true" type="xsd:string" /><xsd:element name="slotsList" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>




condition In tns:condition string type value that specifies the selection criteria in a where clause following Master Rule Language syntax and convention

Note: MRL syntax is case sensitive. Refer to the BMC Impact Manager Knowledge Base Reference Guide for guidelines on using MRL.





QueryComponentsByStatus


The QueryComponentsByStatus operation queries for service components that

■ 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


WSDL for QueryComponentsByStatus operation

WSDL message for QueryComponentsByStatus

<wsdl:operation name="QueryComponentsByStatus" parameterOrder="inargs"><wsdl:input message="tns:QueryComponentsByStatus_Request"/><wsdl:output message="tns:QueryComponentsByStatus_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryComponentsByStatus_Request"> <wsdl:part element="elems:QueryComponentsByStatus" name="inargs"/></wsdl:message><wsdl:message name="QueryComponentsByStatus_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>



XSD schema for request and response for QueryComponentsByStatus

Parameters for QueryComponentsByStatus

<xsd:element name="QueryComponentsByStatus"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="lStatus" nillable="true" type="xsd:string" /><xsd:element name="hStatus" nillable="true" type="xsd:string" /><xsd:element name="baseClass" nillable="true" type="xsd:string" /><xsd:element name="getSubclasses" type="xsd:boolean" /><xsd:element name="slotsList" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>




lStatus In tns:cStatusLow string type value that indicates the lowest MC_SM_COMPONENT_STATUS value to be selected

If you enter only a value for the lStatus, the call selects statuses that are equal to or greater than the lowest status.


QueryData

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.

hStatus In tns:cStatusHigh 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 In tns:baseClass string type that indicates the base class to be selected. Its default is BMC_AssetBase.

getSubClasses In tns:getSubClasses 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






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.

WSDL for QueryData operation

WSDL message for QueryData

XSD schema for request and response for QueryData

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.

<wsdl:operation name="QueryData" parameterOrder="inargs"><wsdl:input message="tns:QueryData_Request"/><wsdl:output message="tns:QueryData_Response"/> <wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryData_Request"> <wsdl:part element="elems:QueryData" name="inargs"/></wsdl:message><wsdl:message name="QueryData_Response"><wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>

<xsd:element name="QueryData"><xsd:complexType><xsd:sequence><xsd:element name="query" nillable="true" type="xsd:string" /><xsd:element name="imname" 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>


QueryEventByID

Parameters for QueryData

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.

WSDL for QueryEventByID

WSDL messages for QueryEventByID


query In tns:query string type that initiates a connection with a specified BMC Impact Manager instance and launches a query for event or data objects




<wsdl:operation name="QueryEventByID" parameterOrder="inargs"><wsdl:input message="tns:QueryEventByID_Request"/><wsdl:output message="tns:QueryEventByID_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryEventByID_Request"> <wsdl:part element="elems:QueryEventByID" name="inargs"/></wsdl:message><wsdl:message name="QueryEventByID_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>


QueryEvents

XSD schema for request and response for QueryEventByID

Parameters for QueryEventByID

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

<xsd:element name="QueryEventByID"><xsd:complexType><xsd:sequence><xsd:element name="eventId" nillable="true" type="xsd:string" /><xsd:element name="imname" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType></xsd:element>



eventID In tns:messageID string type that specifies the universal event ID (mc_ueid) of the event that is being queried





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.

WSDL for QueryEvents operation

WSDL messages for QueryEvents

XSD schema for request and response for QueryEvents

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.

<wsdl:operation name="QueryEvents" parameterOrder="inargs"><wsdl:input message="tns:QueryEvents_Request"/><wsdl:output message="tns:QueryEvents_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryEvents_Request"> <wsdl:part element="elems:QueryEvents" name="inargs"/></wsdl:message><wsdl:message name="QueryEvents_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>

<xsd:element name="QueryEvents"><xsd:complexType><xsd:sequence><xsd:element name="query" nillable="true" type="xsd:string" /><xsd:element name="imname" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType></xsd:element>



QueryEventsByDate

Parameters for QueryEvents

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.

WSDL for QueryEventsByDate operation

WSDL message for QueryEventsByDate


query In tns:query string type that initiates a connection with a specified BMC Impact Manager instance and launches a query for event or data objects




<wsdl:operation name="QueryEventsByDate" parameterOrder="inargs"><wsdl:input message="tns:QueryEventsByDate_Request"/><wsdl:output message="tns:QueryEventsByDate_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryEventsByDate_Request"> <wsdl:part element="elems:QueryEventsByDate" name="inargs"/></wsdl:message><wsdl:message name="QueryEventsByDate_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>


QueryEventsByDate

XSD schema for request and response for QueryEventsByDate

Parameters for QueryEventsByDate

<xsd:element name="QueryEventsByDate"><xsd:complexType><xsd:sequence><xsd:element name="startDate" nillable="true" type="xsd:dateTime" /><xsd:element name="endDate" nillable="true" type="xsd:dateTime" /><xsd:element name="classNames" nillable="true" type="xsd:string" /><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="slotsList" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>



startDate In tns:startDate dateTime type that defines a specific date and time, usually in GMT. It defines the starting point in a date range.

endDate In tns:endDate dateTime type that defines a specific date and time, usually in GMT. It defines the ending point in a date range.

classNames In tns:classNames string type that refers to a specific message class which defines a group of related events



resultHandle Out resultHandle string type that specifies an ID used to identify and track a specific client query



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:

■ mc_udid ■ status ■ CLASS ■ HomeCell

■ shadow_cells


WSDL for QueryModelImpact operation

WSDL messages for QueryModelImpact

<wsdl:operation name="QueryModelImpact" parameterOrder="inargs"><wsdl:input message="tns:QueryModelImpact_Request"/><wsdl:output message="tns:QueryModelImpact_Response"/> <wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryModelImpact_Request"> <wsdl:part element="elems:QueryModelImpact" name="inargs"/></wsdl:message><wsdl:message name="QueryModelImpact_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>


QueryModelImpact

XSD schema for request and response for QueryModelImpact

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









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:

■ mc_udid ■ status ■ CLASS ■ HomeCell

■ shadow_cells


WSDL for QueryModelPossibleRootCauses operation

WSDL messages for QueryModelPossibleRootCauses

<wsdl:operation name="QueryModelPossibleRootCauses" parameterOrder="inargs"><wsdl:input message="tns:QueryModelPossibleRootCauses_Request"/><wsdl:output message="tns:QueryModelPossibleRootCauses_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="QueryModelPossibleRootCauses_Request"> <wsdl:part element="elems:QueryModelPossibleRootCauses" name="inargs"/></wsdl:message><wsdl:message name="QueryModelPossibleRootCauses_Response"> <wsdl:part element="elems:QueryResultHandle_output" name="outargs"/></wsdl:message>



XSD schema for request and response for QueryModelPossibleRootCauses

Parameters for QueryModelPossibleRootCauses

<xsd:element name="QueryModelPossibleRootCauses"><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:element name="trueCause" type="xsd:boolean" /></xsd:sequence></xsd:complexType></xsd:element>




componentId In tns:componentCauseId

string type that contains the universal data ID (mc_udid) of the component object



RegisterStateChange

RegisterStateChange

The RegisterStateChange operation registers your integration with a SIM cell, which enables you to receive state change events.

WSDL for RegisterStateChange operation

trueCause In tns:trueCause 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.



<wsdl:operation name="RegisterStateChange" parameterOrder="inargs"><wsdl:input message="tns:RegisterStateChange_Request"/><wsdl:output message="tns:RegisterStateChange_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>



RegisterStateChange

WSDL message for RegisterStateChange

XSD schema for request and response for RegisterStateChange

Parameters for RegisterStateChange

<wsdl:message name="RegisterStateChange_Request"><wsdl:part element="elems:RegisterStateChange" name="inargs"/></wsdl:message><wsdl:message name="RegisterStateChange_Response"><wsdl:part element="elems:RegisterStateChange_output" name="outargs"/></wsdl:message>

<xsd:element name="RegisterStateChange"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="serverName" nillable="true" type="xsd:string" /><xsd:element name="changeType" type="types:StateChangeType" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="RegisterStateChange_output"><xsd:complexType><xsd:sequence><xsd:element name="registrationID" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>



serverName In tns:serverName string type that specifies the name of the BMC II Web Services server that will be receiving the state change events


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.

WSDL for RetrieveQueryResults operation

WSDL message for RetrieveQueryResults

changeType In tns:StateChangeType_element

indicates an array of possible state change event types. Valid values include

■ COMPONENT_CHANGE = 1■ COMPONENT_DELETE = 2■ RELATIONSHIP_CHANGE = 4■ RELATIONSHIP_DELETE = 8■ SC_ALL = 15

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

<wsdl:operation name="RetrieveQueryResults" parameterOrder="inargs"><wsdl:input message="tns:RetrieveQueryResults_Request"/><wsdl:output message="tns:RetrieveQueryResults_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="RetrieveQueryResults_Request"> <wsdl:part element="elems:RetrieveQueryResults" name="inargs"/></wsdl:message><wsdl:message name="RetrieveQueryResults_Response"> <wsdl:part element="elems:RetrieveQueryResults_output" name="outargs"/></wsdl:message>




XSD schema for request and response for RetrieveQueryResults

Parameters for RetrieveQueryResults

<xsd:element name="RetrieveQueryResults"><xsd:complexType><xsd:sequence><xsd:element name="retrieveResultHandle" nillable="true" type="xsd:string" /><xsd:element name="startIndex" type="xsd:long" /><xsd:element name="timeout" type="xsd:int" /><xsd:element name="num_of_events" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="RetrieveQueryResults_output"><xsd:complexType><xsd:sequence><xsd:element name="results" type="btypes:TableOf_NameValue" /><xsd:element name="num_of_events" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element>



In tns:retrieveResultHandle

string type that contains the ID returned by the server’s response to the initial query request. This ID is attached to all query requests in this cycle.

startIndex In tns:startIndex integer that identifies the starting point from which the number of query results are returned

timeout In tns:timeout integer that defines the duration for which the client waits for a response to its query from the BMC II Web Services server. If no response to the query is received, then this query request is terminated

num_of_results In/Out tns:num_of_results As the input argument, this is the integer that specifies the number of results the client seeks to receive per polling call. As the output argument, it indicates the number of results that the server is able to return.

results Out bypes:NameValueTable_element

the query results that the server is able to return


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.

WSDL for SendEvent operation

WSDL message for SendEvent

XSD schema for request and response for SendEvent

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

<wsdl:operation name="SendEvent" parameterOrder="inargs"><wsdl:input message="tns:SendEvent_Request"/><wsdl:output message="tns:SendEvent_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="SendEvent_Request"> <wsdl:part element="elems:SendEvent" name="inargs"/></wsdl:message><wsdl:message name="SendEvent_Response"> <wsdl:part element="elems:SendEvent_output" name="outargs"/></wsdl:message>

<element name="SendEvent_output"><complexType><sequence> <element name="response" nillable="true" type="xsd:string" /> </sequence> </complexType></element>


SetMaintenanceMode

Parameters for SendEvent

SetMaintenanceMode

The SetMaintenanceMode operation sends a request to place a specified component in maintenance mode.


connection In tns:connection a long integer representing a connection handle ID

message In tns:message an event or data type. This is a string value that extends the ArrayOf_NameValue type, which lists the name-value pairs available to the event description.

timeout In tns:timeout an integer type. It specifies the time that the send operation is to wait for a response from the instance before attempting to reconnect.

messageClass In tns:messageClass string that specifies the name of the class of the event or data. The value can be any valid class name.

messageType In tns:messageType type of message that the Web Service client can exchange with the Web Service and the BMC Impact Manager instance. The message contains the event or data object. The message type can be any of the following enumerated values:

■ MSG_TYPE_NONE■ MSG_TYPE_NEW_EVENT■ MSG_TYPE_MOD_EVENT■ MSG_TYPE_NEW_DATA■ MSG_TYPE_OVERWRITE_DATA■ MSG_TYPE_MOD_DATA

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

WSDL for SetMaintenanceMode operation

WSDL messages for SetMaintenanceMode

XSD schema for request and response for SetMaintenanceMode

Parameters for SetMaintenanceMode

<wsdl:operation name="SetMaintenanceMode" parameterOrder="inargs"><wsdl:input message="tns:SetMaintenanceMode_Request"/><wsdl:output message="tns:SetMaintenanceMode_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="SetMaintenanceMode_Request"> <wsdl:part element="elems:SetMaintenanceMode" name="inargs"/></wsdl:message><wsdl:message name="SetMaintenanceMode_Response"> <wsdl:part element="elems:SetMaintenanceMode_output" name="outargs"/></wsdl:message>

<xsd:element name="SetMaintenanceMode"><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="setOrCleared" nillable="true" type="xsd:int" /><xsd:element name="modeToSet" nillable="true" type="xsd:string" /><xsd:element name="comment" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="SetMaintenanceMode_output"><xsd:complexType><xsd:sequence><xsd:element name="errorCode" nillable="true" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element>





SetManualStatus

SetManualStatus

The SetManualStatus operation sends a request to set a designated manual status on the specified component.

WSDL for SetManualStatus operation

WSDL message for SetManualStatus

setOrCleared In tns:setOrCleared Boolean indicator (true/false) that indicates whether the specified component is available to have its maintenance mode set

modeToSet In tns:modeToSet string description of the maintenance mode

comment In tns:comment string that describes the reason for setting or clearing the current maintenance mode

errorCode Out tns:errorCode integer that identifies a C API error code

<wsdl:operation name="SetManualStatus" parameterOrder="inargs"><wsdl:input message="tns:SetManualStatus_Request"/><wsdl:output message="tns:SetManualStatus_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="SetManualStatus_Request"> <wsdl:part element="elems:SetManualStatus" name="inargs"/></wsdl:message><wsdl:message name="SetManualStatus_Response"> <wsdl:part element="elems:SetManualStatus_output" name="outargs"/></wsdl:message>



Subscribe

XSD schema for request and response for SetManualStatus

Parameters for SetManualStatus

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.

<xsd:element name="SetManualStatus"><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="statusSet" nillable="true" type="xsd:int" /><xsd:element name="componentStatus" nillable="true" type="xsd:string" /><xsd:element name="comment" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="SetManualStatus_output"><xsd:complexType><xsd:sequence><xsd:element name="errorCode" nillable="true" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element>




componentStatus

In tns:componentStatus string type that specifies the manually defined status of the component

comment In tns:comment string that describes the reason for setting or clearing the current maintenance mod

errorCode Out tns:errorCode integer that identifies a web services error


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.

WSDL for Subscribe operation

WSDL message for Subscribe

XSD schema for request and response for Subscribe

<wsdl:operation name="Subscribe" parameterOrder="inargs"><wsdl:input message="tns:Subscribe_Request"/><wsdl:output message="tns:Subscribe_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="Subscribe_Request"> <wsdl:part element="elems:Subscribe" name="inargs"/></wsdl:message><wsdl:message name="Subscribe_Response"> <wsdl:part element="elems:NoValue_output" name="outargs"/></wsdl:message>

<element name="Subscribe"> <complexType> <sequence> <element name="filterName" nillable="true" type="xsd:string" /> <element name="context" nillable="true" type="xsd:string" /> <element name="callbackURL" nillable="true" type="xsd:string" /> <element name="reliable" type="xsd:boolean" /> </sequence> </complexType></element>


UnregisterStateChange

Parameters for Subscribe

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.

WSDL for UnregisterStateChange operation

WSDL message for UnregisterStateChange


filterName In tns:filterName string type that identifies the name of the event filter that the client has selected. The client is requesting to subscribe to the events that match the criteria specified by the event filter.


reliable In tns:reliable Boolean indicator (true/false) that shows whether the subscription request uses guaranteed delivery

<wsdl:operation name="UnregisterStateChange" parameterOrder="inargs"><wsdl:input message="tns:UnregisterStateChange_Request"/><wsdl:output message="tns:UnregisterStateChange_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>

<wsdl:message name="UnregisterStateChange_Request"> <wsdl:part element="elems:UnregisterStateChange" name="inargs"/></wsdl:message><wsdl:message name="UnregisterStateChange_Response"> <wsdl:part element="elems:UnregisterStateChange_output" name="outargs"/></wsdl:message>


Unsubscribe

XSD schema for request and response for UnregisterStateChange

Parameters for UnregisterStateChange

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.

WSDL for Unsubscribe operation

<xsd:element name="UnregisterStateChange"><xsd:complexType><xsd:sequence><xsd:element name="imname" nillable="true" type="xsd:string"/><xsd:element name="registrationID" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element><xsd:element name="UnregisterStateChange_output"><xsd:complexType><xsd:sequence><xsd:element name="resultCode" type="xsd:int" /></xsd:sequence></xsd:complexType></xsd:element>



registrationID In tns:regID integer that is assigned to this registration request

resultCode Out tns:resultCode integer that specifies the server response to the unregister state change request

<wsdl:operation name="Unsubscribe" parameterOrder="inargs"><wsdl:input message="tns:Unsubscribe_Request"/><wsdl:output message="tns:Unsubscribe_Response"/><wsdl:fault message="tns:Execution_Fault" name="Execution_Fault"/></wsdl:operation>


Unsubscribe

WSDL message for Unsubscribe

XSD schema for request and response for Unsubscribe

Parameters for Unsubscribe

<wsdl:message name="Unsubscribe_Request"> <wsdl:part element="elems:Unsubscribe" name="inargs"/></wsdl:message><wsdl:message name="Unsubscribe_Response"> <wsdl:part element="elems:NoValue_output" name="outargs"/></wsdl:message>

<xsd:element name="Unsubscribe"><xsd:complexType><xsd:sequence><xsd:element name="filterName" nillable="true" type="xsd:string" /><xsd:element name="context" nillable="true" type="xsd:string" /></xsd:sequence></xsd:complexType></xsd:element>


filterName In tns:filterName string type that identifies the name of the event filter that the client has selected. The client is requesting to unsubscribe from the events that match the criteria specified by the event filter.



Unsubscribe


C h a p t e r C
C BMC Impact Manager Service
This appendix describes the BMC Impact Manager service that can be accessed through the Impact Manager port.

The BMC Impact Manager service consists of the single port Impact Manager. This port specifies where you can access the Impact Manager binding, through which the portType operations and messages are transmitted. The binding, and therefore the service, can be accessed via the endpoint (URI) described by the location attribute of the soap:address child element of the Impact Manager port.

The service element of the ImpactManager.wsdl is declared below:

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.

<wsdl:service name=”ImpactManager”><wsdl:port name=”ImpactManager” binding=”tns:ImpactManager”><soap:address location:”urn:unknown-location-uri”/></wsdl:port></wsdl:service>

<soap: address location:”http://abc:6070/imapi”/>

Appendix C BMC Impact Manager Service 151

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 fileA file that specifies the order in which a directory’s files are to be loaded and read by a BMC Impact Manager instance.

.map file See adapter map file.

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

AAcknowledge

The event operation action that acknowledges the existence of an event. See also local action.

Acknowledged statusThe event status that results from an Acknowledge event operation action; it means that an operator has acknowledged the event's existence.

Glossary 153

http://www.w3.org/TR/ws-gloss


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

adapterA 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 instanceAn 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 fileA text file that defines the translation of a message between one event format and another. It is also known as a .map file.

administratorThe person responsible for administrative tasks within the product.

aliasSee service component alias.

APISee Application Program Interface (API).

Application Program Interface (API)A set of externalized functions that allow interaction with an application.

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



attributeA characteristic or property of an object, such as a common data model service model component class. An attribute may contain a value.

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

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


BMC IMSee 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) productAn 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 ServicesA 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 instanceAn installation of the BMC Impact Manager product on a host computer. Compare with cell.

BMC Impact Publishing serverThe 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 PortalThe BMC Portal console module that you use to monitor the status of business services and their components. See also console module.

BMC Impact ReportingThe BMC Impact Solutions component that you use to create and view long-term reports.

BMC PortalA 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 FoundationThe base component on which BMC Software reporting systems and solutions are built.



BMC Service Impact Manager (BMC SIM)A real-time service impact management product license package that provides technologies for both service impact and event management (SIEM). BMC SIM identifies related applications and the underlying systems and databases of any software or infrastructure component and ties systems-level monitoring to the supported business services, enabling IT personnel to respond quickly to problems that threaten the delivery of business services.

Business Service Management (BSM)A dynamic method for connecting key business services to the IT systems that manage them. BSM enables users to understand and predict how technology changes will affect their business, and how changes in the business affect the IT infrastructure.

Ccell

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

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

componentA 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


physical assets, and service components, which are components that participate in the delivery of business services.

component instanceA named component that represents an actual IT resource.

conditionA 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 moduleA product that plugs into the BMC Portal.

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

Ddata class

A BAROC class that is a child of the base event class, DATA, and that defines a type of data.

datastoreA central place in which an aggregation of data is kept and maintained in an organized way.

data typeA 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 modelA working version of the service model that contains both published and unpublished elements.

duplicate eventA 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 collectorA special type of collector that, in response to events, can add or remove event collectors from the cell during runtime.



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

EEnableTrace parameter

A configurable parameter in the BMC II Web Services server that, when set to true, activates the server logging facility.

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

endpointA specific location (uniform resource identifier) for accessing a web service using a specific protocol and data format. See also service.

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

eventA structured message passed to and from cells in a BMC Impact environment. It is an instance of an event class.

event class1. 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 collectorAn 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


event collector ruleA 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 managementThe collection and correlation of events across an enterprise to enable IT operations to focus the proper resources on the most critical events.

event management policyOne 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 propagationThe act of forwarding events and maintaining their synchronization among multiple BMC Impact Manager instances (cells).

event selectorThe 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 fileThe 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 ruleAn 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.



Ffacet

In the BMC Impact Manager product, a specific attribute of a class slot that either controls the values that the slot can have or controls aspects of a class instance’s processing.

In XML, a single defining aspect of a value for a data type. It is characterized as fundamental, which defines the data type, or constraining, which restricts the values of a data type. See also data type.

fault messageIn 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 ruleAn 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.

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

Ggateway

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 fileA special file that controls the propagation and synchronization of events to a BMC Impact Manager Integration product.

Hheartbeat

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 intervalThe time between heartbeats; the period of the heartbeat.

Glossary 161


Iimpact

An assessed measure of the effect that an incident, fault, or other change will or may have on business operations or service levels.

ImpactManager.wsdlThe 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 eventAn 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 propagationThe 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 relationshipA 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.

instance1. 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 productSee BMC Impact Integration (BMC II) product.

Kkb 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 slotA slot whose value is compared during searches.

Knowledge Base (KB) A collection of information that forms the intelligence of a BMC Impact Manager instance and enables it to process events and perform service-impact-management activities. This



information includes event class definitions, Service-Model component definitions, record definitions, interface definitions, collector definitions, data associations, and processing rules.

Lload file

See .load file.

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

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

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


mcell.dir fileThe 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 fileThe 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 fileThe 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 fileA 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_udidSee universal data identifier (mc_udid).

Nnamespace

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.

nodeA BMC Impact Manager instance that can receive only events originating on the local host system.

non-local actionA user-initiated action that does not execute on the operations console host machine.

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



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

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

operationIn Web Services Description Language, a set of messages related to a single web service action.

Pphase (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 instanceA 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.

portA specific communication channel in TCP/IP networking. Ports are identified by numbers. BMC Impact Manager communicates using the ports specified during installation.

port typeIn Web Services Description Language, a logical grouping of operations and their messages. It defines the public entry point for client applications.

portingThe process of translating or converting software to run in a different operating environment.

Glossary 165


Propagate ruleAn 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 eventAn event that is forwarded from one cell to another cell or to an Integration product during the Propagate phase of event processing.

propagationSee event propagation.

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

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

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

repositoryThe storage facility in which BMC Impact Manager event information is stored.

root cause analysisThe process of monitoring events and correlating event data to identify the true cause of a problem.

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



Sselector

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

serviceIn 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 aliasA name that is assigned to a service component instance and used in associating an event type with the component instance. You add an alias to a service component instance’s definition in the Service Model Editor. A service component instance can have several different aliases to enable different event types to be associated with it.

slotAn attribute in a BAROC class definition. A class definition consists of one or more slots. Each slot has a data type and can have specific attributes, called facets, that can control the values that the slot can have or control aspects of a class instance’s processing. A class that is a subclass to another class inherits all the slots of the parent class.

SOAP encodingA 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 generatorA 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.

SSLSecure 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 eventA generated event type that records changes in a component’s status. State change events never participate in component status computation.

Glossary 167


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

subscribeIn an event distribution system, a consumer action of registering to receive (subscribe to) specified events. Contrast with publish.

subscription tableA 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 servicesA 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.

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

UUDDI

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.



WWASP 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 selectorA 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 clauseA 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


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



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

Aadministration

BMC Impact Integration Web Services server 44editing iiws.selector 58iiws.conf file 58iiws.selector file 44

ArrayOf_Byte, element description 91ArrayOf_CellInfo, element description 97ArrayOf_ClassDefInfo, element description 98ArrayOf_Double, element description 92ArrayOf_Event, element description 95ArrayOf_Float, element description 92ArrayOf_Int, element description 91ArrayOf_Long, element description 91ArrayOf_NameValue, element description 94ArrayOf_Short, element description 91ArrayOf_SlotDefInfo, element description 100ArrayOf_SMComponent, element definition 98ArrayOf_String, element description 92audience

presumed knowledge 43roles 43

BbaseClass

element description 66parameter 116, 126

BasicTypes.xsd 63BMC Developer Connection 15BMC Impact Integration Web Services APIs 43

BMC Impact Integration Web Services Developer’s Kit 43BMC Impact Integration Web Services server 43

adminstration 44selector processing 45

BMC Impact Manager 151BMC Software, contacting 2BMCII_BUFFER_MODE_DEFAULT, description 87BMCII_BUFFER_MODE_HIGH, description 87BMCII_BUFFER_MODE_LOW, description 87BMCII_BUFFER_MODE_NONE, description 87bmcii_loadSelectorSet function, failure 46buffering

buffer, maximum size 59MessageBufferReconnectInterval parameter 59MessageBufferSize parameter 59reconnect interval 59

bufferType, element description 66ByteArray derived complex type 89

Ccell_hostname element, description 96cell_name element, description 96cell_type element, description 96CellInfo 96cellInfo_Array

element description 66parameter 110

ChangeDate parameter, message selector set header 49changeType parameter 139ClassDefInfo, element description 97classDefInfo_Array


classDefInfo_element, description 67classDefs parameter 117classes, specifying in translation maps 52className


classNameselement description 67parameter 132

classOnlyelement description 68

Index 171


parameter 117comment


componentCauseIdelement description 68

componentIdelement description 69parameter 118, 120, 134, 136, 143, 145

componentStatuselement description 69parameter 145

componentStatusIdelement description 69parameter 121

conditionelement description 69parameter 123

configuringiiws.conf 59

Connectoperation 105

connecting, maximum reconnect interval 59connection

element description 70connectionId


contextelement description 70parameter 105, 111, 147, 149

context_nioelement description 71

CStatuselement description 100

Cstatus_elementelement description 71

CStatusHighelement description 71

CStatusLowelement description 72

custom complex typesArrayOf_CellInfo 97ArrayOf_ClassDefInfo 98ArrayOf_SlotDefInfo 100ArrayOf_SMComponent 98CellInfo 96ClassDefInfo 97CStatus 100GetEventsResponse 100GetQueryResultResponse 101SlotDefInfo 99SMComponent 98StateChangeType 101

customer support 3

172 BMC ProactiveNet Performance Management Web

Ddata types

arrays 90complex 89mapping to other languages 102overview 63simple 85

data types, XSDimported schemas 63

DataTypeelement description 88

deleteBufferelement description 72parameter 107

Description parameterin message selector header 50in message selector set header 49

Disconnectoperation 107

DoubleArray derived complex type 89

Eelement descriptions

general 64summary table 64

embedding message selectors 46Enable parameter

in message selector header 50in message selector set header 49

encryption_key element, description 97endDate


EndQueryoperation 108

errorCodeelement description 73parameter 144, 145

Event complex type, description 95Event.xsd 63Event_element derived complex type 90EventArray_element derived complex type 90eventId


FFailOnMissingSlot message selector header parameter 50failure

matching 50selection 50

filterName

Services Developer Guide


element description 73parameter 105, 111, 113, 147, 149

FloatArray derived conplex type 89formatting

%, using in message selectors 54message 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 54in message selectors 51slot.slotname 52

GGetCellInfo

operation 109GetEvents

operation 110GetEventsResponse complex type, description 100GetEventsResponse_element

element description 74GetFilterNames

operation 112GetQueryResultCount

operation 113GetQueryResultResponse complex type, description 101GetQueryResultResponse_element

element description 74getSubclasses


Hhost names, specifying in message selectors 52hStatus

parameter 126

Iiiws.conf, configuration parameters 59iiws.selector file 44, 58IIWSGatewayserver event listener

port 24ImapiTypes.xsd 63

IMBufferTypecustom values 87element description 87

imFailureelement description 74

IMMessageTypecustom values 86element description 86

imnameelement description 75parameter 120, 125, 129, 131, 132, 143, 145

Impact Manager port type, definition 104IntArray derived complex type 89

Llong_Response


LongArray derived complex type 89lStatus

parameter 125

Mmcell.dir

description 62editing 62

messageelement description 75parameter 142

message buffer capacity 59message propagation

MessageBufferKeepSent parameter 59MessageBufferKeepWait parameter 59MessageBufferReconnectInterval parameter 59MessageBufferResendCount parameter 59MessageBufferSize parameter 59

message selectorscharacteristics 46content 51embedding 53embedding with $doselector 46file, characteristics 46formatting 48header requirement 50header sample 51message selector set header 48name 50operators 55parameters, header 50parameters, set header 49set header requirement 48set header sample 49sets, description 46

Index 173


sets, formatting 48sets, headers 48sets, naming 46slots, missing 50syntax rules 46time, specifying settings 54

MessageBufferKeepSent 59MessageBufferKeepSent configuration parameter 59MessageBufferKeepWait configuration parameter 59MessageBufferReconnectInterval configuration parameter

description 59MessageBufferResendCount configuration parameter 59MessageBufferSize configuration parameter

description 59messageClass


messageIDelement description 76

messageTypeelement description 76parameter 142

modeToSetelement description 77parameter 144

MSG_TYPE_MOD_DATA, description 86MSG_TYPE_MOD_EVENT, description 86MSG_TYPE_NEW_DATA, description 86MSG_TYPE_NEW_EVENT, description 86MSG_TYPE_NONE, description 86MSG_TYPE_OVERWRITE_DATA, description 86

NName_Value_element derived complex type 90NameValue

child elements 93element description 93

NameValue_Array_element derived complex type 90nameValueTable_element

parameter 140NameValueTable_element derived complex type 90num_of_components

element description 77num_of_events


num_of_resultselement description 78parameter 140

OonlyImpacted

element description 78


parameter 120operations

Connect 105Disconnect 107EndQuery 108GetCellInfo 109GetEvents 110GetFilterNames 112GetQueryResultCount 113QueryClassDefinitions 115QueryComponent 117QueryComponentEvents 118QueryComponentsByCondition 122QueryComponentsByStatus 124QueryComponentStatus 120QueryData 126QueryEventByID 128QueryEventsByDate 131QueryModelImpact 133QueryModelPossibleRootCauses 135RegisterStateChange 137RetrieveQueryResults 139SendEvent 141SetMaintenanceMode 142SetManualStatus 144Subscribe 145UnregisterStateChange 147Unsubscribe 148

Pparameters

ChangeDate 49Description 49Enable 49, 50FailOnMissingSlot 50FormatVersion 49message selector set header list 49MessageBufferKeepWait 59MessageBufferReconnectInterval 59MessageBufferResendCount 59MessageBufferSize 59PersistencyCleanupGarbageThreshold 60PersistencyCleanupSizeThreshold 60PersistencyDisconnectRemoveMessages 60PersistencyEnabled 60PersistencyFileName 60PersistencyLevel 60SelectorHeader 50SelectorSetName 49Version 49

passwordelement description 78

PersistencyCleanupGarbageThreshold configuration parameter 60



PersistencyCleanupSizeThreshold configuration parameter 60

PersistencyDisconnectRemoveMessages configuration parameter 60

PersistencyEnabled configuration parameter 60PersistencyFileName configuration parameters 60PersistencyLevel configuration parameter

description 60port element, description 96ports

IIWSGatewayserver event listener 24printf function 54product support 3

Qquery


QueryClassDefinitionsoperation 115

QueryComponentoperation 117

QueryComponentEventsoperation 118

QueryComponentsByConditionoperation 122

QueryComponentsByStatusoperation 124

QueryComponentStatusoperation 120

QueryDataoperation 126

QueryEventByIDoperation 128

QueryEventsByDateoperation 131

QueryModeelement description 88

queryModeparameter 116

QueryMode_elementelement description 79

QueryModelImpactoperation 133

QueryModelPossibleRootCausesoperation 135

RregID

element description 79RegisterStateChange

operation 137registrationID

parameter 139, 148reliable


responseparameter 112

responseIdparameter 142

resultCodeelement description 80parameter 148

resultCountparameter 114

resultHandleelement description 80parameter 109, 114, 120, 123, 126, 129, 131, 132, 137

RetrieveQueryResultsoperation 139

retrieveResultHandleelement description 81parameter 140

Sschemas, imported 63SecurityToken

element description 81SelectorName message selector header parameter 50selectors

iiws.selector file 58in subscription requests 45overview 44

selectorset_name.message selector file 46SelectorSetName message selector set header parameter 49SendEvent

operation 141ServerName

element description 81serverName

parameter 138SetMaintenanceMode

operation 142SetManualStatus

operation 144SetOrCleared

element description 82setOrCleared

parameter 144ShortArray derived complex type 89slot.slotname function 52SlotDefInfo

element description 99SlotDefInfo_Array

element description 82SlotDefInfo_element


Index 175


slotsin message selectors 51missing from message selectors 50selecting, by value 52

SlotsListelement description 82

slotsListparameter 120, 123, 126, 132, 134, 136

SMComponentelement description 98

SMComponent_elementelement description 83

SMComponentArray_elementelement description 83

source-code generatorcompiling ImpactManager.wsdl 32

StartDateelement description 83

startDateparameter 132

StartIndexelement description 84

startIndexparameter 140

StateChangeTypeelement description 101

StateChangeType_elementelement description 84

strftime 54string_Response

parameter 120, 123, 126, 132, 137StringArray derived complex type 89Subscribe

operation 145support, customer 3

TTableOf_NameValue

element description 94technical support 3TIBCO platform 18time, using in message selectors 54time_t, in message selector files 54timeout

element description 84parameter 114, 140, 142

translationclass names, specifying 52host names, specifying 52

trueCauseelement description 85parameter 137

trusted_servers element, description 97


UUnregisterStateChange

operation 147Unsubscribe

operation 148userName


Vvalue complex type, description 93value_element derived complex type 90Version, message selector set header parameter 49

WWeb services client

programming language 31summary of steps 32

XXSD data types

imported schemas 63


BMC SOFTWARE – SDK LICENSE AGREEMENT BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, THE ENTITY OR INDIVIDUALENTERING INTO THIS AGREEMENT AGREES TO BE BOUND BY THE FOLLOWING TERMS, IF YOU DO NOT AGREE WITH ANY OF THESE TERMS,DO NOT INSTALL OR USE THE BMC MODULES AND PROMPTLY RETURN THE BMC MODULES TO BMC. IF YOU REJECT THIS AGREEMENT YOUWILL NOT ACQUIRE ANY LICENSE TO USE THE BMC MODULES.

SCOPE OF AGREEMENT. This Agreement is between the entity or individual entering into this Agreement (“You”) and BMC Software, Inc. (“BMC”). ThisAgreement governs Your use of the BMC Modules, unless You agreed to a web-based license agreement with BMC when ordering the BMC Modules, inwhich case that web-based license agreement governs the use of the BMC Modules. As used herein, “Complementary Product” means any product of Youthat embeds or is dependent for execution upon a BMC Module.

LICENSE. BMC grants You a non-exclusive, non-transferable, personal license (“License”) for one person (the “Developer”) (a) to copy and operate the BMCModules for the sole purpose of designing, developing and testing Complementary Products, provided that You acknowledge and agree that the right ofembedding does not include a right of distribution, and (b) to copy and operate Complementary Products (including any BMC Modules embedded therein)solely for Your internal production purposes. You may not and agree not to: (i) copy the BMC Modules or the Complementary Products except as expresslypermitted in the immediately foregoing sentence, (ii) distribute, resell, rent or lease the BMC Modules or the Complementary Products, (iii) use the BMCModules for production purposes except as expressly permitted with respect to embedded BMC Modules in the immediately foregoing sentence, (iv)disassemble or reverse engineer any BMC Module, or decompile or otherwise attempt to derive any BMC Module source code from executable code, except tothe extent expressly permitted by applicable law despite this limitation, (v) release any information to any third parties on the functionality or performance ofthe BMC Modules without BMC's prior written consent, or (vi) provide a third party with the results of any functional evaluation, or benchmarking orperformance tests, without BMC's prior written approval. Additional usage restrictions may apply to certain third-party files or programs embedded in aBMC Module – applicable installation instructions or release notes may contain the relevant details. Notwithstanding anything in this Agreement to thecontrary, the licenses granted in this Agreement (A) do not grant You the right to use any BMC Module (such rights, if any, are granted under a separatelicense), (B) do not extend to any rights under any patents or patent applications under which BMC has any rights, and (C) do not extend to any use of theBMC Modules in combination with any product, service or software other than the Complementary Product for which it is registered and approved.

FEES. You agree to pay any shipping or handling fees associated with the BMC Modules. You are responsible for taxes, if any.

TERMINATION. This Agreement terminates automatically if You breach any of its terms. Either party may terminate this Agreement without cause on 30days prior written notice. Upon termination, You must uninstall the BMC Modules, and either certify their destruction or return them to BMC.

OWNERSHIP. BMC, or its affiliates or licensors, retains all right, title and interest in the BMC Modules and copies thereof, and any intellectual property,informational, industrial property and proprietary rights therein. BMC neither grants nor otherwise transfers any rights of ownership in the BMC Modules toYou. The BMC Modules are protected by applicable copyright, trade secret, patent and other intellectual and industrial property laws. As between You andBMC, You retain all right, title and interest in any intellectual property, information, industrial property and proprietary rights in the ComplementaryProducts, excluding and subject to those contained in the BMC Modules.

CONFIDENTIAL AND PROPRIETARY INFORMATION. The BMC Modules contain valuable confidential information and trade secrets of BMC. You maynot use the BMC Modules other than as specifically allowed under the license granted in this Agreement. You may not disclose the BMC Modules or any partthereof, to third parties, except that (i) You may disclose the BMC Modules or parts thereof to Developer if Developer has obligations of confidentiality whichare at least as protective of BMC’s confidential information and trade secrets as the provisions of this Agreement and if Developer’s use of the BMC Modulesis consistent with the terms of this Agreement, and (ii) if You use a Complementary Product internally for production purposes, You may disclose the BMCModules or parts thereof to its employees who are under obligations of confidentiality at least as protective of BMC’s confidential information and tradesecrets as the provisions of this Agreement, whose use of the BMC Modules is consistent with the terms of this Agreement, and who need to receive suchdisclosure in order to install, operate, support or maintain the Complementary BMC Modules. You agree to use all reasonable efforts to prevent theunauthorized use, copying, publication or dissemination of any BMC Module.

WARRANTY DISCLAIMER. THE BMC MODULES ARE PROVIDED “AS IS”, WITH ALL FAULTS. BMC, ITS AFFILIATES AND LICENSORSSPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND QUIET ENJOYMENT. BMC DOES NOT WARRANT THAT THE OPERATION OFTHE BMC MODULES OR THE COMPLEMENTARY PRODUCTS WILL BE UNINTERRUPTED, VIRUS OR ERROR FREE, OR THAT THERE ARE NODEFECTS.

LIMITS ON BMC’S LIABILITY. IN NO EVENT WILL BMC, ITS AFFILIATES OR LICENSORS, BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL,PUNITIVE OR CONSEQUENTIAL DAMAGES RELATING TO OR ARISING OUT OF THIS AGREEMENT, THE BMC MODULES AND/OR ANYCOMPLEMENTARY PRODUCT (INCLUDING WITHOUT LIMITATION LOST PROFITS, LOST COMPUTER USAGE TIME, AND DAMAGE OR LOSS OFUSE OF DATA), EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND IRRESPECTIVE OF ANY NEGLIGENCE OF BMC OR WHETHERSUCH DAMAGES RESULT FROM A CLAIM ARISING UNDER TORT OR CONTRACT LAW. BMC’S LIABILITY FOR DIRECT DAMAGES IS LIMITED TOTHE GREATER OF (I) THE AMOUNT PAID BY YOU FOR THE LICENSE TO THE BMC MODULE, IF ANY, AND (II) $1000.

VERIFICATION. If requested by BMC, You will deliver to BMC written certification relating to Your use of the BMC Modules and/or the ComplementaryProducts in compliance with the terms of this Agreement. BMC may audit Your use of the BMC Modules and/or Complementary Products to confirm suchcompliance.

EXPORT CONTROLS. You will cooperate with BMC as reasonably necessary to ensure compliance with the laws and regulations of the United States and allother relevant countries, relating to exports and re-exports (“Export Laws”). You may not import, export, re-export or transfer, directly or indirectly, includingvia remote access, any part of the BMC Modules, or any other BMC information or technology, in violation of any such laws and regulations, or without anywritten governmental authorization required under applicable Export Laws. Neither the BMC Modules nor the underlying information or technology may bedownloaded or otherwise provided or made available, either directly or indirectly, (i) into Cuba, Iran, Libya, Sudan or any other country subject to U.S. tradesanctions, to individuals or entities controlled by such countries, or to nationals or residents of such countries other than nationals who are lawfully admittedpermanent residents of countries not subject to such sanctions; or (ii) to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals andblocked persons or the U.S. Commerce Department’s Table of Denial Orders. BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES”OR USING THE BMC MODULES, YOU AGREE TO THE FOREGOING AND REPRESENT AND WARRANT THAT YOU ARE NOT LOCATED IN, UNDERTHE CONTOL OF, OR A NATIONAL OR RESIDENT OF ANY SUCH COUNTRY OR ON ANY SUCH LIST.

DISPUTE RESOLUTION AND GOVERNING LAW. ANY CONTROVERSY OR CLAIM ARISING OUT OF THIS AGREEMENT, OR THE BREACH HEREOF,WILL BE SETTLED BY ARBITRATION ADMINISTERED BY THE AMERICAN ARBITRATION ASSOCIATION UNDER ITS COMMERCIALARBITRATION RULES IN HOUSTON, TEXAS IN ENGLISH. THE ARBITRATOR MUST FILE ALL FINDINGS WITHIN 30 DAYS AFTER THE FINALARBITRATION HEARING. JUDGMENT ON ANY AWARD RENDERED BY THE ARBITRATOR MAY BE ENTERED IN ANY COURT HAVINGJURISDICTION THEREOF. NOTHING CONTAINED IN THIS SECTION WILL LIMIT BMC'S ABILITY TO SEEK EQUITABLE RELIEF IN ANY COURT.THE PARTIES WILL ARBITRATE DISPUTES IN CONFIDENCE. THIS AGREEMENT WILL BE GOVERNED BY THE SUBSTANTIVE LAWS OF THE STATEOF TEXAS. CHOICE OF LAW RULES OF ANY JURISDICTION AND THE UNITED NATIONS CONVENTION ON CONTRACTS FOR THEINTERNATIONAL SALE OF GOODS WILL NOT APPLY.

U.S. GOVERNMENT RESTRICTED RIGHTS. UNPUBLISHED – RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use,duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013,DFARS 227.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer isBMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

MISCELLANEOUS TERMS. This Agreement constitutes the entire agreement between You and BMC relating to the matters covered hereby, and supersedesany prior or contemporaneous negotiations or agreements, whether oral or written, concerning the BMC Modules and any related subject matter. ThisAgreement may be modified only in a mutually signed, whether in writing or electronic, agreement between You and BMC. Neither Developer nor You mayassign 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 ofYour assets. Should any provision of this Agreement be invalid, or unenforceable, the remainder of the provisions will remain in effect. The parties haveagreed that this Agreement and the documents related thereto be drawn up in the English language. Les parties exigent que la présente convention ainsi queles documents qui s’y rattachent soient rédigés en anglais.

BY OPENING THE PACKAGE, INSTALLING, PRESSING “AGREE” OR “YES” OR USING THE BMC MODULES, YOU ACKNOWLEDGE AND AGREETHAT YOUR AUTHORIZED REPRESENTATIVE HAS READ THIS AGREEMENT AND THAT YOU INTEND TO BE BOUND HEREBY, AS IF YOURAUTHORIZED REPRESENTATIVE HAD SIGNED THIS AGREEMENT IN WRITING. THE INDIVIDUAL EXECUTING THIS AGREEMENT WARRANTSTHAT HE OR SHE HAS THE AUTHORITY TO ACCEPT THE TERMS OF THIS AGREEMENT FOR YOU AND ON HIS OR HER OWN BEHALF.

Third-Party Product TermsThe following terms apply to third-party products that are included with or in a BMC Software product as described in the BMC Software, Inc., LicenseAgreement that is applicable to the BMC Software product.

OpenSSl LicenseCopyright (C) 1995 Tim Hudson ([email protected]) All rights reserved.

This package is documentation for the SSLeay implementation that was written by Eric Young ([email protected]). The documentation was written by TimHudson ([email protected]).

This documentation can be distributed free for commercial and non-commercial use as long as the following conditions are aheared to. The followingconditions apply to all the documentation found in this distribution. Copyright remains Tim Hudson's, and as such any Copyright notices in thedocumentation are not to be removed. If this documentation is used in a product, Tim Hudson should be given attribution as the author of thisdocumentation.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code and documentation must retain the copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this documentation must display the following acknowledgement: This documentation was written by Tim Hudson ([email protected])

THIS DOCUMENTATION IS PROVIDED BY TIM HUDSON ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALLTHE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS 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 THEPOSSIBILITY OF SUCH DAMAGE.

*202694**202694**202694**202694*

*209476*

Impact Integration Web Services Server Developer Guide

Documents

Transcript of Impact Integration Web Services Server Developer Guide