BAO 20.11.02 Application Adapters Space

Copyright 2009 -- 2011 BladeLogic, Inc.
BMC, BMC Software, the BMC logos, and other BMC marks are trademarks or registered trademarks of BMC Software, Inc. in the U.S. and/or certain other countries. BladeLogic and the BladeLogic logo are trademarks or registered trademarks of BladeLogic, Inc. in the U.S. and/or certain other countries. All other trademarks or registered trademarks are the property of their respective owners. BMC Software Confidential.
BMC Atrium Orchestrator Application Adapters 20.11.02
Copyright 2009 - 2011 BladeLogic, 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. BladeLogic and the BladeLogic logo are the exclusive properties of BladeLogic, Inc. The BladeLogic trademark is registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BladeLogic 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. ADD APP ADAPTER LICENSE INFORMATION IT Infrastructure Library is a registered trademark of the Office of Government Commerce and is used here by BMC Software, Inc., under license from and with the permission of OGC. ITIL is a Registered Trade Mark of the Office of Government Commerce in the United Kingdom and other countries. Linux is the registered trademark of Linus Torvalds. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. SAP is a trademark or registered trademark of SAP AG in Germany and in several other countries. UNIX is the registered trademark of The Open Group in the US and other countries. 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 legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHEDRIGHTS 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. BMC Software Inc. 2101 CityWest Blvd, Houston TX 77042-2827, USA 713 918 8800 Customer Support: 800 537 1813 or contact your local support center
Copyright 2009 -- 2011 BladeLogic, Inc. BMC, BMC Software, the BMC logos, and other BMC marks are trademarks or registered trademarks of BMC Software, Inc. in the U.S. and/or certain other countries. BladeLogic and the BladeLogic logo are trademarks or registered trademarks of BladeLogic, Inc. in the U.S. and/or certain other countries. All other trademarks or registered trademarks are the property of their respective owners. BMC Software Confidential.
1. Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.1 What's new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.1.1 License entitlements for BMC Atrium Orchestrator Application Adapters . . . . . . . . . . . . . . . . . . 17 1.1.2 Version 20.11.02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.1.2.1 Enhancements in version 20.11.02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.1.2.1.1 Introducing the BMC Atrium Orchestrator Application Adapter for DELL Advanced Infrastructure Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.1.2.1.2 Introducing the BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . 19 1.1.2.1.3 Introducing the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.1.2.1.4 Changes to BMC Atrium Orchestrator Application Adapter for VMware Infrastructure . . . 20 1.1.2.1.5 Changes to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.1.2.1.6 Changes to BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . . . . . . 21 1.1.2.1.7 Changes to BMC Atrium Orchestrator Application Adapter for HP Operations Manager . 21 1.1.2.1.8 Changes to BMC Atrium Orchestrator Application Adapter for HP Service Manager . 21 1.1.2.1.9 Changes to BMC Atrium Orchestrator Application Adapters for HP AssetCenter, HP ServiceCenter, NetApp Rapid Cloning Utility, VMware vCloud, BMC BladeLogic Network Automation, and VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 1.1.2.1.10 Changes to BMC Atrium Orchestrator Application Adapter for Service-now . . . . . . . 22 1.1.2.1.11 Changes to BMC Atrium Orchestrator Application Adapter for Microsoft Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 1.1.2.2 Corrected problems in version 20.11.02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 1.1.3 Documentation updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.1.3.1 Documentation updates for December 12, 2011 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.1.4 Product alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.1.4.1 BMC BladeLogic Server Automation adapter fails to start when configured to use the CLI tunnel interface (ADAPTER-5102) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.2 Key concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1.2.1 Adapter overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1.2.2 Adapter module lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 1.3 Working with Grid Manager and BMC Atrium Orchestrator Development Studio . . . . . . . . . . . . . . . . . 26 1.3.1 Importing a module from the repository to BMC Atrium Orchestrator Development Studio . . . . . 26 1.3.2 Enabling an adapter on a peer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 1.3.3 Exporting the adapter module to the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 1.3.4 Activating a module on the grid manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 1.4 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 1.4.1 Recommended installation environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 1.4.2 Installation paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 1.4.3 Using the GUI to install BMC Atrium Orchestrator content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 1.4.4 Using command-line options to install BMC Atrium Orchestrator content . . . . . . . . . . . . . . . . . . 31 1.4.4.1 Silent installation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 1.4.4.2 Installation properties for content options files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 1.4.4.3 Sample content options file templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1.4.4.4 Creating an options file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1.4.4.5 Executing a silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1.5 BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.5.1 Peer synchronization required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.5.2 Configuring the BMC Atrium Orchestrator Application Adapter for Amazon EC2 adapter . . . . . . 42 1.5.3 BMC Atrium Orchestrator Application Adapter for Amazon EC2 module . . . . . . . . . . . . . . . . . . . 46 1.5.3.1 Top-level processes for the BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . 46 1.5.3.2 Setup_Validation directory for BMC Atrium Orchestrator Application Adapter for Amazon EC2 directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 1.5.3.3 Utilities directory for the BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . 47 1.5.3.4 v1.0 directory for the BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . . . 47 1.5.3.5 Adapter_Actions directory for the BMC Atrium Orchestrator Application Adapter for Amazon
EC2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4 Actor adapter requests and responses for the BMC Atrium Orchestrator Application Adapter for Amazon EC2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.1 Amazon EC2 actor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.2 Adapter requests and responses for Security Group operations . . . . . . . . . . . . . . . . . . . . . 1.5.4.2.1 Request and response for Revoke Security Group Ingress operation . . . . . . . . . . . . 1.5.4.2.2 Request and response for Delete Security Group operation . . . . . . . . . . . . . . . . . . . . 1.5.4.2.3 Request and response for Authorize Security Group Ingress operation . . . . . . . . . . . 1.5.4.2.4 Request and response for Create Security Group operation . . . . . . . . . . . . . . . . . . . . 1.5.4.2.5 Request and response for Describe Security Groups operation . . . . . . . . . . . . . . . . . 1.5.4.3 Adapter requests and responses for Elastic IP Address operations . . . . . . . . . . . . . . . . . . 1.5.4.3.1 Request and response for the Allocate Address operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.3.2 Request and response for the Associate Address operation . . . . . . . . . . . . . . . . . . . . 1.5.4.3.3 Request and response for the Disassociate Address operation . . . . . . . . . . . . . . . . . 1.5.4.3.4 Request and response for Describe Addresses operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.3.5 Request and response for the Release Address operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.4 Adapter requests and responses for Instance operations . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.4.1 Request and response for Describe Instances operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.4.2 Request and response for the Stop Instances operation . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.4.3 Request and response for the Describe Instance Attribute operation . . . . . . . . . . . . . 1.5.4.4.4 Request and response for the Terminate Instances operation . . . . . . . . . . . . . . . . . . 1.5.4.4.5 Request and response for the Reset Instance Attribute operation . . . . . . . . . . . . . . . 1.5.4.4.6 Request and response for the Run Instances operation . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.4.7 Request and response for the Start Instances operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.4.8 Request and response for the Reboot Instances operation . . . . . . . . . . . . . . . . . . . . 1.5.4.4.9 Request and response for the Modify Instance Attribute operation . . . . . . . . . . . . . . . 1.5.4.5 Adapter request and response for the Amazon Machine Image operations . . . . . . . . . . . . 1.5.4.5.1 Request and response for the Deregister Image operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.5.2 Request and response for the Describe Images operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.5.3 Request and response for the Modify Image Attribute operation . . . . . . . . . . . . . . . . 1.5.4.5.4 Request and response for the Reset Image Attribute operation . . . . . . . . . . . . . . . . . 1.5.4.5.5 Request and response for the Create Image operation . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.5.6 Request and response for the Describe Image Attribute operation . . . . . . . . . . . . . . . 1.5.4.5.7 Request and response for the Register Image operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.6 Adapter requests and responses for Monitoring operations . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.6.1 Request and response for the Unmonitor Instances operation . . . . . . . . . . . . . . . . . . 1.5.4.6.2 Request and response for Monitor Instances operation . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.7 Adapter requests and responses for the Utility operation . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.7.1 Request and response for the Get Console Output operation . . . . . . . . . . . . . . . . . . . 1.5.4.8 Adapter requests and responses for Elastic Block Store operations . . . . . . . . . . . . . . . . . . 1.5.4.8.1 Request and response for the Create Snapshot operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.8.2 Request and response for the Create Volume operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.8.3 Request and response for the Describe Snapshots operation . . . . . . . . . . . . . . . . . . 1.5.4.8.4 Request and response for the Delete Snapshot operation . . . . . . . . . . . . . . . . . . . . . 1.5.4.8.5 Request and response for the Describe Snapshot Attribute operation . . . . . . . . . . . . 1.5.4.8.6 Request and response for the Modify Snapshot Attribute operation . . . . . . . . . . . . . . 1.5.4.8.7 Request and response for the Describe Volumes operation . . . . . . . . . . . . . . . . . . . . 1.5.4.8.8 Request and response for the Attach Volume operation . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.8.9 Request and response for the Detach Volume operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.8.10 Request and response for the Reset Snapshot Attribute operation . . . . . . . . . . . . . 1.5.4.8.11 Request and response for the Delete Volume operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.9 Adapter requests and responses for the Windows operations . . . . . . . . . . . . . . . . . . . . . . . 1.5.4.9.1 Request and response for the Cancel Bundle Task operation . . . . . . . . . . . . . . . . . . 1.5.4.9.2 Request and response for the Describe Bundle Tasks operation . . . . . . . . . . . . . . . . 1.5.4.9.3 Request and response for the Bundle Instance operation . . . . . . . . . . . . . . . . . . . . . . 1.5.4.9.4 Request and response for the Get Password Data operation . . . . . . . . . . . . . . . . . . . 1.5.4.10 Adapter request and response for the Regions and Availability Zones operations . . . . . . 1.5.4.10.1 Request and response for the Describe Availability Zones operation . . . . . . . . . . . . 1.5.4.10.2 Request and response for the Describe Regions operation . . . . . . . . . . . . . . . . . . .
49 50 50 52 53 57 59 63 65 67 67 70 72 74 76 78 78 82 84 87 90 92 100 103 105 108 108 110 113 116 118 121 124 128 128 130 132 132 135 135 137 140 143 145 147 150 153 155 158 160 162 162 164 167 170 173 173 175
1.5.4.11 Adapter requests and responses for Key pair operations . . . . . . . . . . . . . . . . . . . . . . . . . 177 1.5.4.11.1 Request and response for the Create Key Pair operation . . . . . . . . . . . . . . . . . . . . . 177 1.5.4.11.2 Request and response for the Delete Key Pair operation . . . . . . . . . . . . . . . . . . . . . 180 1.5.4.11.3 Request and response for the Describe Key Pairs operation . . . . . . . . . . . . . . . . . . 182 1.5.5 EBS Storage Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 1.5.5.1 Storage Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 1.6 BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 1.6.1 Configuring the BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . . . . . . . . . 186 1.6.2 BMC Atrium Orchestrator Application Adapter for Amazon S3 module . . . . . . . . . . . . . . . . . . . . 188 1.6.2.1 Adapter_Actions directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 1.6.2.2 Setup_Validation directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 1.6.2.3 Utilities directory for BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . . 189 1.6.2.4 v1.0 directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3 . . . . . 189 1.6.3 BMC Atrium Orchestrator Application Adapter for Amazon S3 actor adapter requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 1.6.3.1 Adapter requests and responses for the Bucket operations . . . . . . . . . . . . . . . . . . . . . . . . 189 1.6.3.1.1 Create Bucket operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 1.6.3.1.2 Delete Bucket operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 1.6.3.1.3 List Bucket Contents operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 1.6.3.2 Adapter requests and responses for the Object operations . . . . . . . . . . . . . . . . . . . . . . . . . 195 1.6.3.2.1 Put Object Inline operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 1.6.3.2.2 Delete Object operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 1.6.3.2.3 Put Object operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 1.6.3.3 Adapter requests and responses for the Service operation . . . . . . . . . . . . . . . . . . . . . . . . . 200 1.6.3.3.1 List All My Buckets operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 1.7 BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . 202 1.7.1 Pre-requisites for the BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . 202 1.7.2 Configuring the BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . 203 1.7.3 BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB module . . . . . . . . . . . . . . 209 1.7.3.1 Top-level processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB 209 1.7.3.1.1 Create Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 1.7.3.1.2 Delete Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 1.7.3.1.3 Find Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 1.7.3.1.4 Update Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 1.7.3.1.5 Get Versions process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 1.7.3.2 SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 1.7.3.3 Utilities directory for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . 226 1.7.3.3.1 Extract From Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 1.7.3.3.2 Set Default Adapter Name process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 1.7.3.3.3 Unsupported Class Type Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 1.7.3.3.4 Unsupported Delete Criteria Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 1.7.3.3.5 Unsupported Entity Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 1.7.3.3.6 Version Error Reporting process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
1.7.3.3.7 ConfigurationItem - Create Instance process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 1.7.3.3.8 ConfigurationItem - Delete Instance process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 1.7.3.4 v2.0 - ConfigurationItem processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 1.7.3.4.1 Create CI Instance process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 1.7.3.4.2 Create Relation Instance process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 1.7.3.4.3 Delete Instance By Instance Name process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . 238 1.7.3.4.4 Delete Instance By InstanceId process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 1.7.3.4.5 Delete Instance By Reconciliation Identity process for v2.0 . . . . . . . . . . . . . . . . . . . . 240 1.7.3.4.6 Find Instance process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 1.7.3.4.7 Update Instance process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 1.7.3.5 v2.0 - GraphQuery process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 1.7.3.5.1 Graph Query process for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 1.7.3.6 v7.5 - ConfigurationItem processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 1.7.3.6.1 Create CI Instance process for v7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 1.7.3.6.2 Delete Instance By Instance Name process for v7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . 254 1.7.3.6.3 Delete Instance By InstanceId process for v7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 1.7.3.6.4 Delete Instance By Reconciliation Identity process for v7.5 . . . . . . . . . . . . . . . . . . . . 256 1.7.3.6.5 Find Instance process for v7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 1.7.3.6.6 Update Instance process for v7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 1.7.4 BMC Atrium Orchestrator features for BMC Atrium CMDB Classes with parameter mapping . . . 264 1.7.4.1 CI classes with mapped parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 1.7.4.2 Relationship classes with mapped parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 1.7.4.3 Enum Value parameter mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 1.7.4.4 Time Value parameter mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 1.7.5 BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB requests and responses for v2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 1.7.5.1 Adapter request and response for the create-instance operation for v2.0 . . . . . . . . . . . . . . 266 1.7.5.2 Adapter request and response for the create-relation-instance operation for v2.0 . . . . . . . 271 1.7.5.3 Adapter request and response for the delete-instance operation for v2.0 . . . . . . . . . . . . . . 277 1.7.5.4 Adapter request and response for the get-instances operation for v2.0 . . . . . . . . . . . . . . . 281 1.7.5.5 Adapter request and response for the set-instance operation for v2.0 . . . . . . . . . . . . . . . . 289 1.7.6 BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB requests and responses for v7.5 and v7.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 1.7.6.1 Adapter request and response for the create-instance operation for v7.5 and 7.6 . . . . . . . 296 1.7.6.2 Adapter request and response for the delete-instance operation for v7.5 and 7.6 . . . . . . . 298 1.7.6.3 Adapter request and response for the get-instances operation for v7.5 and 7.6 . . . . . . . . . 300 1.7.6.4 Adapter request and response for the set-instance operation for v7.5 and 7.6 . . . . . . . . . . 305 1.8 BMC Atrium Orchestrator Application Adapter for BMC Event Manager . . . . . . . . . . . . . . . . . . . . . . . 307 1.8.1 BMC Atrium Orchestrator actor adapter for BMC Event Manager . . . . . . . . . . . . . . . . . . . . . . . . 307 1.8.2 Supported versions of BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 1.8.3 Configuring the BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . 308 1.8.4 BMC Atrium Orchestrator Application Adapter for BEM module . . . . . . . . . . . . . . . . . . . . . . . . . 312 1.8.4.1 Top-level processes for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . 312 1.8.4.1.1 Process inputs for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . 312 1.8.4.1.2 Create Items process for BMC Atrium Orchestrator Application Adapter for BEM . . . 313 1.8.4.1.3 Find Items process for BMC Atrium Orchestrator Application Adapter for BEM . . . . . 315 1.8.4.1.4 Perform Operations process for BMC Atrium Orchestrator Application Adapter for BEM . 315 1.8.4.1.5 Update Items process for BMC Atrium Orchestrator Application Adapter for BEM . . . 316 1.8.4.2 SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BEM . . . . 317 1.8.4.3 Utilities directory for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . 317 1.8.4.4 Version directories for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . 317 1.8.5 Actor adapter requests and responses for BMC Atrium Orchestrator Application Adapter for BEM . 318
1.8.5.1 Adapter request and response for the Create operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 1.8.5.1.1 Create Event operation for BMC Atrium Orchestrator Application Adapter for BEM . . 318 1.8.5.2 Adapter requests and responses for the Maintenance Mode operations for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 1.8.5.2.1 Disable Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 1.8.5.2.2 Resume Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 1.8.5.3 Adapter requests and responses for the Retrieve operations for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 1.8.5.3.1 Retrieve Events operation for BMC Atrium Orchestrator Application Adapter for BEM . . . 325 1.8.5.3.2 Retrieve Event by Date operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 1.8.5.3.3 Retrieve Events by Component operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 1.8.5.3.4 Retrieve Events by ID operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 1.8.5.4 Adapter requests and responses for the Update operations for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 1.8.5.4.1 Update Event operation for BMC Atrium Orchestrator Application Adapter for BEM . 339 1.8.5.4.2 Acknowledge Event operation for BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 1.8.5.4.3 Annotate Event operation for BMC Atrium Orchestrator Application Adapter for BEM . . . 344 1.8.5.4.4 Assign Event operation for BMC Atrium Orchestrator Application Adapter for BEM . . 346 1.8.5.4.5 Close Event operation for BMC Atrium Orchestrator Application Adapter for BEM . . . 348 1.8.5.4.6 Reopen Event operation for BMC Atrium Orchestrator Application Adapter for BEM . 350 1.8.5.4.7 Set Event Priority operation for BMC Atrium Orchestrator Application Adapter for BEM . 352 1.8.5.4.8 Set Action Result operation for BMC Atrium Orchestrator Application Adapter for BEM . 354 1.8.6 BMC Atrium Orchestrator Monitor Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 1.8.6.1 Setting up events for the BMC Atrium Orchestrator Monitor Adapter for BEM . . . . . . . . . . 358 1.8.6.2 Propagating events from the cells to the gateway for the BMC Atrium Orchestrator Monitor Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 1.8.6.3 Module configuration for BMC Event Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 1.8.6.4 Propagation rules for the maintenance mode for the BMC Atrium Orchestrator Monitor Adapter for BEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 1.8.6.5 BMC Atrium Orchestrator Monitor Adapter for BEM Event . . . . . . . . . . . . . . . . . . . . . . . . . 360 1.8.7 Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BEM . . . . . . . . . . 361 1.9 BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation . . . . . . . . . . 361 1.9.1 Supported versions of BMC BladeLogic Network Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 1.9.2 Configuring the BMC BladeLogic Network Automation adapter . . . . . . . . . . . . . . . . . . . . . . . . . . 362 1.9.3 BMC BladeLogic Network Automation application adapter module . . . . . . . . . . . . . . . . . . . . . . . 366 1.9.3.1 Top-level processes for the BMC BladeLogic Network Automation adapter . . . . . . . . . . . . 366 1.9.3.2 Setup Validation directory for the BMC BladeLogic Network Automation adapter . . . . . . . . 368 1.9.3.3 Utilities directory for the BMC BladeLogic Network Automation adapter . . . . . . . . . . . . . . . 368 1.9.3.4 Version directories for the BMC BladeLogic Network Automation adapter . . . . . . . . . . . . . 368 1.9.3.4.1 Process inputs for the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 1.9.4 Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 1.9.4.1 Authentication Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 1.9.4.1.1 Request and response for the Login operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 1.9.4.1.2 Request and response for the Logout operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 1.9.4.2 Device Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 1.9.4.2.1 Request and response for the Get Devices operation . . . . . . . . . . . . . . . . . . . . . . . . . 374
1.9.4.2.2 Request and response for the Get Configuration operation . . . . . . . . . . . . . . . . . . . . 1.9.4.2.3 Request and response for the Add Device operation . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.2.4 Request and response for the Delete Device operation . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.3 Report Service operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.3.1 Request and response for the Send Job Summary Report Email operation . . . . . . . . 1.9.4.4 Job Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.4.1 Request and response for the Job Approval or Job Rejection operation . . . . . . . . . . 1.9.4.4.2 Request and response for the Retrieve Job Status by JobID operation . . . . . . . . . . . 1.9.4.5 Span Action Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.5.1 Request and response for the Device Rollback or Merge By Config Type operation . 1.9.4.5.2 Request and response for the Merge Compliant All Assigned operation . . . . . . . . . . 1.9.4.5.3 Request and response for the Merge Compliant By Rule operation . . . . . . . . . . . . . . 1.9.4.5.4 Request and response for the Merge Compliant By Rule Set operation . . . . . . . . . . . 1.9.4.5.5 Request and response for the Merge By Adhoc Template operation . . . . . . . . . . . . . 1.9.4.5.6 Request and response for the Merge By Template Group operation . . . . . . . . . . . . . 1.9.4.5.7 Request and response for the Perform Backup operation . . . . . . . . . . . . . . . . . . . . . . 1.9.4.5.8 Request and response for the Perform Custom Action operation . . . . . . . . . . . . . . . . 1.9.4.5.9 Request and response for the Commit operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.5.10 Request and response for the Mark as Trusted by Config Date operation . . . . . . . . 1.9.4.5.11 Request and response for Restore By Template Group operation . . . . . . . . . . . . . . 1.9.4.5.12 Request and response for the Get Span Action Results operations . . . . . . . . . . . . . 1.9.4.6 Events service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.6.1 Request and response for the Log Events operation . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.7 Substitution Parameter Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.7.1 Request and response for the Add Substitution Parameter operation . . . . . . . . . . . . 1.9.4.7.2 Request and response for the Modify Substitution Parameter operation . . . . . . . . . . 1.9.4.7.3 Request and response for the Get Substitution Parameter by Name operation . . . . . 1.9.4.8 Template Group Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.8.1 Request and response for the Modify Template Group operation . . . . . . . . . . . . . . . . 1.9.4.8.2 Request and response for the Get Template Group By Name operation . . . . . . . . . . 1.9.4.9 Job Approval Type Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.9.1 Request and response for the Get Job Approval Types operation . . . . . . . . . . . . . . . 1.9.4.10 Group Service operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.10.1 Request and response for the Get Simple Groups operation . . . . . . . . . . . . . . . . . . 1.9.4.11 Predefined Jobs operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.11.1 Request and response for the Get All Predefined Job Names operation . . . . . . . . . 1.9.4.11.2 Request and response for the Get Predefined Job Names operation . . . . . . . . . . . . 1.9.4.11.3 Request and response for the Get Predefined Job Parameter Types operation . . . . 1.9.4.11.4 Request and response for the Submit Job operation . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.11.5 Request and response for the Validate Predefined Job Parameters operation . . . . . 1.9.4.11.6 Request and response for the Get All Shared Runtime Parameters operation . . . . . 1.9.4.12 Firewall Service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9.4.12.1 Request and response for the Get All Firewall Rules operation . . . . . . . . . . . . . . . . 1.9.4.12.2 Request and response for the Overwrite Firewall Rules operation . . . . . . . . . . . . . . 1.9.5 Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.10 BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation . . . . . . . . . . 1.10.1 Getting started with the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . . . . . . . . 1.10.1.1 Prerequisites for the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . . . . . . 1.10.1.2 Supported versions of BMC BladeLogic Server Automation . . . . . . . . . . . . . . . . . . . . . . . 1.10.1.3 Configuring the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.10.1.3.1 Adapter configuration samples and elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.10.1.3.2 Setting up authentication for BMC BladeLogic SSO . . . . . . . . . . . . . . . . . . . . . . . . . 1.10.2 Application adapter module for the BMC BladeLogic Server Automation adapter . . . . . . . . . . . 1.10.2.1 Setup Validation directory for BMC BladeLogic Server Automation adapter . . . . . . . . . . . 1.10.2.2 Version directories for the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . 1.10.2.3 Utilities directory for the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . . . 1.10.2.4 Working with the BMC BladeLogic Server Automation adapter module . . . . . . . . . . . . . .
384 387 394 395 395 398 399 401 403 404 410 415 420 425 430 435 440 446 451 456 461 463 463 466 466 469 471 472 472 476 479 479 480 480 484 485 486 487 490 496 499 500 500 503 508 509 510 510 510 511 512 519 523 523 523 523 523
1.10.2.4.1 How to create a BMC BladeLogic Deploy Job that deploys a BMC BladeLogic Package 524 1.10.2.5 Executing NSH commands and scripts using the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 1.10.2.6 Modifying the command timeout for the BMC BladeLogic Server Automation adapter . . . 530 1.10.3 Actor adapter requests and responses for the BMC BladeLogic Server Automation adapter . . 530 1.10.3.1 Supported adapter request formats for the BMC BladeLogic Server Automation adapter 531 1.10.3.2 Actor adapter requests and responses for executing BLCLI commands . . . . . . . . . . . . . . 531 1.10.3.3 Actor adapter requests and responses for executing scripts and commands on NSH . . . 537 1.10.3.4 Actor adapter requests and responses for executing Jython scripts . . . . . . . . . . . . . . . . . 542 1.10.3.5 Actor adapter request and response with different command formats . . . . . . . . . . . . . . . . 545 1.10.3.6 Actor adapter requests and responses using the BladeLogic Web Services interface . . . 549 1.10.4 Troubleshooting the BMC BladeLogic Server Automation adapter . . . . . . . . . . . . . . . . . . . . . . 552 1.10.4.1 Configuration errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 1.10.4.2 Executing any operation in an Oracle Solaris environment creates a core dump file . . . . 552 1.10.4.3 Persistent connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 1.10.4.3.1 Lifespan of a cached connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 1.11 BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . 554 1.11.1 BMC Atrium Orchestrator actor adapter for BMC ProactiveNet Performance Manager . . . . . . 554 1.11.2 Supported versions of BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . 555 1.11.3 Configuring the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 1.11.4 BMC ProactiveNet Performance Manager application adapter module . . . . . . . . . . . . . . . . . . . 559 1.11.4.1 SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 1.11.4.2 Version directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 1.11.4.3 Top-level processes for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 1.11.4.3.1 Create Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 1.11.4.3.2 Find Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 1.11.4.3.3 Perform Operations process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 1.11.4.3.4 Update Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 1.11.4.4 Process inputs for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 1.11.4.5 Utilities directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 1.11.5 Actor adapter requests and responses for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 1.11.5.1 Adapter request and response for the Create operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . 565 1.11.5.1.1 Create Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 1.11.5.2 Adapter requests and responses for the Maintenance Mode operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . 569 1.11.5.2.1 Disable Event Reporting operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 1.11.5.2.2 Resume Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 1.11.5.3 Adapter requests and responses for the Retrieve operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . 572 1.11.5.3.1 Retrieve Events operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 1.11.5.3.2 Retrieve Event by Date operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 1.11.5.3.3 Retrieve Events by Component operation for BMC Atrium Orchestrator Application
Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 1.11.5.3.4 Retrieve Events by ID operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 1.11.5.4 Adapter requests and responses for the Update operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . 588 1.11.5.4.1 Update Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 1.11.5.4.2 Acknowledge Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 1.11.5.4.3 Annotate Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 1.11.5.4.4 Assign Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 1.11.5.4.5 Close Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 1.11.5.4.6 Reopen Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 1.11.5.4.7 Set Event Priority operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 1.11.5.4.8 Set Action Result operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 1.11.6 BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager . . . . 608 1.11.6.1 Setting up events for the BMC Atrium Orchestrator Monitor Adapter for the BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 1.11.6.2 Propagating events from the cells to the gateway for the BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 1.11.6.3 Module configuration for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . 610 1.11.6.4 Propagation rules for the maintenance mode for BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610 1.11.6.5 BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 1.11.7 Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performanance Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 1.12 BMC Atrium Orchestrator application adapter for BMC Remedy AR System . . . . . . . . . . . . . . . . . . . 612 1.12.1 Using the Integration Mapping Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 1.12.2 Supported versions for the BMC Remedy AR System adapter . . . . . . . . . . . . . . . . . . . . . . . . . 612 1.12.3 Configuring the BMC Atrium Orchestrator Application Adapter for BMC Remedy System . . . . 612 1.12.4 BMC Remedy AR System application adapter module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 1.12.4.1 Top-level processes for the BMC Remedy AR System adapter . . . . . . . . . . . . . . . . . . . . 624 1.12.4.1.1 Create Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 1.12.4.1.2 Delete Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 1.12.4.1.3 Find Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 1.12.4.1.4 Query Update Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 1.12.4.1.5 Update Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 1.12.4.1.6 Query Server Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 1.12.4.2 Version directories for the BMC Remedy AR System adapter . . . . . . . . . . . . . . . . . . . . . . 635 1.12.4.2.1 Delete Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 1.12.4.2.2 Get Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 1.12.4.2.3 Get Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 1.12.4.2.4 Insert Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 1.12.4.2.5 Query Update Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 1.12.4.2.6 Reset Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 1.12.4.2.7 Update Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 1.12.4.2.8 Batch Insert Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 1.12.4.2.9 Batch Delete Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 1.12.4.2.10 Batch Update Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 1.12.4.2.11 Batch Query Update Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 1.12.4.3 Utilities directory for the BMC Remedy AR System adapter . . . . . . . . . . . . . . . . . . . . . . . 650 1.12.4.3.1 Translate Keys to Remedy IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
10
1.12.4.4 Setup Validation directory for the BMC Remedy AR System adapter . . . . . . . . . . . . . . . . 652 1.12.5 Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 1.12.5.1 Peer mapping feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 1.12.5.2 Actor adapter requests for the BMC Atrium Orchestrator application adapter for Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 1.12.5.2.1 Adapter request and response with schema-retrieve . . . . . . . . . . . . . . . . . . . . . . . . 653 1.12.5.2.2 Adapter request and response with set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 1.12.5.2.3 Adapter request and response with update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 1.12.5.2.4 Adapter request and response with get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 1.12.5.2.5 Adapter request and response with query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 1.12.5.2.6 Adapter request and response with query-update . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 1.12.5.2.7 Adapter request and response with delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 1.12.5.2.8 Adapter request and response with reset-cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 1.12.5.2.9 Adapter request and response with attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 1.12.6 BMC Remedy AR System monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 1.12.6.1 Configure a Notify Filter in BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 1.12.6.2 Adapter event for the BMC Remedy AR System monitor adapter . . . . . . . . . . . . . . . . . . . 670 1.13 BMC Atrium Orchestrator Application Adapter for Solaris Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 1.13.1 Supported version of Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 1.13.2 Configuring the BMC Atrium Orchestrator Application Adapter for Solaris Zones . . . . . . . . . . . 672 1.13.3 BMC Atrium Orchestrator Application Adapter for Solaris Zones module . . . . . . . . . . . . . . . . . 676 1.13.3.1 Top-level processes for the BMC Atrium Orchestrator Application Adapter for Solaris Zones 676 1.13.3.2 SetupValidation directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 1.13.3.3 Utilities directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones 677 1.13.3.4 v10.4 directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones . . 677 1.13.4 Actor adapter requests and responses for the BMC Atrium Orchestrator Application Adapter for Solaris Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 1.13.4.1 Adapter requests and responses for the Basic Zone operations . . . . . . . . . . . . . . . . . . . . 679 1.13.4.1.1 Request and response for the Boot Zone operation . . . . . . . . . . . . . . . . . . . . . . . . . 679 1.13.4.1.2 Request and response for the Reboot Zone operation . . . . . . . . . . . . . . . . . . . . . . . 681 1.13.4.1.3 Request and response for the Install Zone operation . . . . . . . . . . . . . . . . . . . . . . . . 683 1.13.4.1.4 Request and response for the Uninstall Zone operation . . . . . . . . . . . . . . . . . . . . . . 685 1.13.4.1.5 Request and response for the Halt Zone operation . . . . . . . . . . . . . . . . . . . . . . . . . . 687 1.13.4.1.6 Request and response for the Ready Zone operation . . . . . . . . . . . . . . . . . . . . . . . . 689 1.13.4.2 Adapter request and response for the Advanced Zone operation . . . . . . . . . . . . . . . . . . . 691 1.13.4.2.1 Adapter request and response for the Advanced Zone operation . . . . . . . . . . . . . . . 691 1.13.4.3 Adapter requests and responses for the Configure Zone operations . . . . . . . . . . . . . . . . 693 1.13.4.3.1 Request and response for the Create Zone operation . . . . . . . . . . . . . . . . . . . . . . . 694 1.13.4.3.2 Request and response for the Create Zone With Custom Settings operation . . . . . . 696 1.13.4.3.3 Request and response for the Create Zone From Template operation . . . . . . . . . . . 704 1.13.4.3.4 Request and response for the Clone Zone operation . . . . . . . . . . . . . . . . . . . . . . . . 706 1.13.4.3.5 Request and response for the Retrieve Zone Configuration operation . . . . . . . . . . . 709 1.13.4.3.6 Request and response for the Update Zone Configuration operation . . . . . . . . . . . . 711 1.13.4.3.7 Request and response for the Delete Zone operation . . . . . . . . . . . . . . . . . . . . . . . . 724 1.14 BMC Atrium Orchestrator Application Adapter for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . 726 1.14.1 Getting started with the BMC Atrium Orchestrator Application Adapter for VMware Infrastructure . 727 1.14.1.1 Supported versions of VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 1.14.1.2 Prerequisites for the BMC Atrium Orchestrator application adapter for VMware Infrastructure 727 1.14.1.3 Configuring the BMC Atrium Orchestrator application adapter for VMware Infrastructure 728 1.14.1.3.1 Configuring the VMware Infrastructure actor adapter . . . . . . . . . . . . . . . . . . . . . . . . 728 1.14.1.3.2 Configuring the VMware Infrastructure event monitor adapter . . . . . . . . . . . . . . . . . 730 1.14.1.3.3 Configuring the VMware Infrastructure SNMP monitor adapter . . . . . . . . . . . . . . . . 734 1.14.2 BMC Atrium Orchestrator Application Adapter for VMware Infrastructure module . . . . . . . . . . . 736 1.14.2.1 Top-level processes for the VMware Infrastructure adapter . . . . . . . . . . . . . . . . . . . . . . . 736
11
1.14.2.2 SetupValidation directory for the VMware Infrastructure adapter . . . . . . . . . . . . . . . . . . . 736 1.14.2.3 Utilities directory for the VMware Infrastructure adapter . . . . . . . . . . . . . . . . . . . . . . . . . . 736 1.14.2.4 Version directories for the VMware Infrastructure adapter . . . . . . . . . . . . . . . . . . . . . . . . . 741 1.14.2.4.1 Process Inputs for the VMware Infrastructure adapter module . . . . . . . . . . . . . . . . . 741 1.14.2.5 VMWare home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 1.14.3 Actor adapter requests and responses for the VMware Infrastructure adapter . . . . . . . . . . . . . 743 1.14.3.1 Adapter requests and responses for Basic VM operations . . . . . . . . . . . . . . . . . . . . . . . . 753 1.14.3.1.1 Request and response for the Power_On_VM operation . . . . . . . . . . . . . . . . . . . . . 753 1.14.3.1.2 Request and response for the Power_Off_VM operation . . . . . . . . . . . . . . . . . . . . . 755 1.14.3.1.3 Request and response for the Suspend_VM operation . . . . . . . . . . . . . . . . . . . . . . . 757 1.14.3.1.4 Request and response for the Resume_VM operation . . . . . . . . . . . . . . . . . . . . . . . 759 1.14.3.1.5 Request and response for the Reset_VM operation . . . . . . . . . . . . . . . . . . . . . . . . . 761 1.14.3.1.6 Request and response for the Restart_Guest_OS operation . . . . . . . . . . . . . . . . . . 763 1.14.3.1.7 Request and response for the Shut_Down_Guest_OS operation . . . . . . . . . . . . . . . 765 1.14.3.2 Adapter requests and responses for Advanced VM operations . . . . . . . . . . . . . . . . . . . . . 766 1.14.3.2.1 Request and response for the Create_VM_Snapshot operation . . . . . . . . . . . . . . . . 767 1.14.3.2.2 Request and response for the Revert_VM_Snapshot operation . . . . . . . . . . . . . . . . 769 1.14.3.2.3 Request and response for the Move_Virtual_Disk operation . . . . . . . . . . . . . . . . . . 771 1.14.3.2.4 Request and response for the Validate_VM_Migration operation . . . . . . . . . . . . . . . 773 1.14.3.2.5 Request and response for the Migrate_VM operation . . . . . . . . . . . . . . . . . . . . . . . . 776 1.14.3.2.6 Request and response for the Relocate_VM operation . . . . . . . . . . . . . . . . . . . . . . . 778 1.14.3.2.7 Request and response for the Acquire_Mks_Ticket operation . . . . . . . . . . . . . . . . . 782 1.14.3.2.8 Request and response for the Retrieve_VM_File_Info operation . . . . . . . . . . . . . . . 784 1.14.3.2.9 Request and response for the Update_VM_Snapshot operation . . . . . . . . . . . . . . . 788 1.14.3.2.10 Request and response for the Delete_VM_Snapshot operation . . . . . . . . . . . . . . . 790 1.14.3.3 Adapter requests and responses for Configure VM operations . . . . . . . . . . . . . . . . . . . . . 792 1.14.3.3.1 Request and response for the Create_VM operation . . . . . . . . . . . . . . . . . . . . . . . . 793 1.14.3.3.2 Request and response for the Create_VM_With_Custom_Settings operation . . . . . 796 1.14.3.3.3 Request and response for the Clone_VM operation . . . . . . . . . . . . . . . . . . . . . . . . . 805 1.14.3.3.4 Request and response for the Clone_VM_With_Custom_Settings operation . . . . . . 808 1.14.3.3.5 Request and response for the Add_Hard_Disk operation . . . . . . . . . . . . . . . . . . . . . 818 1.14.3.3.6 Request and response for the Retrieve_VM_Configuration operation . . . . . . . . . . . 821 1.14.3.3.7 Request and response for the Add_Ethernet_Adapter operation . . . . . . . . . . . . . . . 832 1.14.3.3.8 Request and response for the Add_CD_ROM operation . . . . . . . . . . . . . . . . . . . . . 836 1.14.3.3.9 Request and response for the Retrieve_CPU_Configuration operation . . . . . . . . . . 839 1.14.3.3.10 Request and response for the Retrieve_Memory_Configuration operation . . . . . . . 841 1.14.3.3.11 Request and response for the Retrieve_Hard_Disk_Configuration operation . . . . . 844 1.14.3.3.12 Request and response for the Retrieve_CD_ROM_Configuration operation . . . . . 846 1.14.3.3.13 Request and response for the Retrieve_Ethernet_Adapter_Configuration operation . . 850 1.14.3.3.14 Request and response for the Update_CD_ROM_Configuration operation . . . . . . 853 1.14.3.3.15 Request and response for the Update_VM_Configuration operation . . . . . . . . . . . 855 1.14.3.3.16 Request and response for the Update_CPU_Configuration operation . . . . . . . . . . 865 1.14.3.3.17 Request and response for the Update_Memory_Configuration operation . . . . . . . 867 1.14.3.3.18 Request and response for the Update_Ethernet_Adapter_Configuration operation . . . 869 1.14.3.3.19 Request and response for the Update_Hard_Disk_Configuration operation . . . . . . 874 1.14.3.3.20 Request and response for the Delete_VM operation . . . . . . . . . . . . . . . . . . . . . . . . 877 1.14.3.3.21 Request and response for the Remove_Hard_Disk operation . . . . . . . . . . . . . . . . 879 1.14.3.3.22 Request and response for the Remove_Ethernet_Adapter operation . . . . . . . . . . . 881 1.14.3.3.23 Request and response for the Remove_CD_ROM operation . . . . . . . . . . . . . . . . . 883 1.14.3.3.24 Request and response for the Export_VM_As_OVF_Template operation . . . . . . . 886 1.14.3.3.25 Request and response for the Import_OVF_Template_As_VM operation . . . . . . . 888 1.14.3.4 Adapter requests and responses for Monitor VM operations . . . . . . . . . . . . . . . . . . . . . . . 891 1.14.3.4.1 Request and response for the Retrieve_VM_CPU_Usage operation . . . . . . . . . . . . 891 1.14.3.4.2 Request and response for the Retrieve_VM_Disk_Usage operation . . . . . . . . . . . . 893 1.14.3.4.3 Request and response for the Retrieve_VM_Memory_Usage operation . . . . . . . . . 896 1.14.3.4.4 Request and response for the Retrieve_VM_Network_Usage operation . . . . . . . . . 899 1.14.3.4.5 Request and response for the Retrieve_VM_Status operation . . . . . . . . . . . . . . . . . 902
12
1.14.3.4.6 Request and response for the Retrieve_Task_Status operation . . . . . . . . . . . . . . . . 904 1.14.3.4.7 Request and response for the Retrieve_VM_Alarm_List operation . . . . . . . . . . . . . . 907 1.14.3.4.8 Request and response for the Delete_VM_Alarm operation . . . . . . . . . . . . . . . . . . . 911 1.14.3.5 Adapter requests and responses for Host operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 1.14.3.5.1 Request and response for the Create_Host operation . . . . . . . . . . . . . . . . . . . . . . . 913 1.14.3.5.2 Request and response for the Add_Host_To_Cluster operation . . . . . . . . . . . . . . . . 915 1.14.3.5.3 Request and response for the Add_Virtual_Switch operation . . . . . . . . . . . . . . . . . . 918 1.14.3.5.4 Request and response for the Add_Virtual_NIC operation . . . . . . . . . . . . . . . . . . . . 921 1.14.3.5.5 Request and response for the Add_Port_Group operation . . . . . . . . . . . . . . . . . . . . 923 1.14.3.5.6 Request and response for the Add_NAS_Datastore operation . . . . . . . . . . . . . . . . . 926 1.14.3.5.7 Request and response for the Add_Vmfs_Datastore operation . . . . . . . . . . . . . . . . 928 1.14.3.5.8 Request and response for the Add_Internet_Scsi_Send_Targets operation . . . . . . 930 1.14.3.5.9 Request and response for the Move_Host_To_Cluster operation . . . . . . . . . . . . . . . 932 1.14.3.5.10 Request and response for the Retrieve_Host_Configuration operation . . . . . . . . . 934 1.14.3.5.11 Request and response for the Retrieve_Host_DVS_Configuration operation . . . . . 938 1.14.3.5.12 Request and response for the Retrieve_Host_Network_Configuration operation . . 941 1.14.3.5.13 Request and response for the Retrieve_Host_Datastore_Configuration operation . 947 1.14.3.5.14 Request and response for the Retrieve_Virtual_Switch_Configuration operation . . 949 1.14.3.5.15 Request and response for the Retrieve_Virtual_NIC_Configuration operation . . . . 953 1.14.3.5.16 Request and response for the Retrieve_Port_Group_Configuration operation . . . . 956 1.14.3.5.17 Request and response for the Retrieve_Available_Disks_For_Vmfs operation . . . 959 1.14.3.5.18 Request and response for the Retrieve_Host_CPU_Usage operation . . . . . . . . . . 962 1.14.3.5.19 Request and response for the Retrieve_Host_Memory_Usage operation . . . . . . . 964 1.14.3.5.20 Request and response for the Retrieve_ESX_Hosts operation . . . . . . . . . . . . . . . . 966 1.14.3.5.21 Request and response for the Retrieve_Host_Scsi_Topology operation . . . . . . . . 969 1.14.3.5.22 Request and response for the Rescan_Hba operation . . . . . . . . . . . . . . . . . . . . . . 973 1.14.3.5.23 Request and response for the Rescan_All_Hba operation . . . . . . . . . . . . . . . . . . . 974 1.14.3.5.24 Request and response for the Update_Host_Network_Configuration operation . . . 976 1.14.3.5.25 Request and response for the Extend_Vmfs_Datastore operation . . . . . . . . . . . . . 984 1.14.3.5.26 Request and response for the Update_Software_Internet_Scsi_Enabled operation . . 987 1.14.3.5.27 Request and response for the Update_Internet_Scsi_Name operation . . . . . . . . . 988 1.14.3.5.28 Request and response for the Remove_Host_From_Cluster operation . . . . . . . . . 990 1.14.3.5.29 Request and response for the Remove_Virtual_Switch operation . . . . . . . . . . . . . 992 1.14.3.5.30 Request and response for the Remove_Virtual_NIC operation . . . . . . . . . . . . . . . . 994 1.14.3.5.31 Request and response for the Remove_Port_Group operation . . . . . . . . . . . . . . . 996 1.14.3.5.32 Request and response for the Remove_Datastore operation . . . . . . . . . . . . . . . . . 998 1.14.3.5.33 Request and response for the Enter_Maintenance_Mode operation . . . . . . . . . . . 1000 1.14.3.5.34 Request and response for the Exit_Maintenance_Mode operation . . . . . . . . . . . . . 1002 1.14.3.6 Adapter requests and responses for Datastore operations . . . . . . . . . . . . . . . . . . . . . . . . 1004 1.14.3.6.1 Request and response for the Retrieve_Datastore_List operation . . . . . . . . . . . . . . 1004 1.14.3.6.2 Request and response for the Retrieve_Datastore_Virtual_Machines operation . . . 1008 1.14.3.6.3 Request and response for the Retrieve_Vmfs_Datastore_Storage_Controller operation 1010 1.14.3.7 Adapter requests and responses for Cluster operations . . . . . . . . . . . . . . . . . . . . . . . . . . 1013 1.14.3.7.1 Request and response for the Retrieve_Cluster_Configuration operation . . . . . . . . 1013 1.14.3.7.2 Request and response for the Retrieve_Cluster_Datastore_Configuration operation . . . 1019 1.14.3.7.3 Request and response for the Retrieve_Clusters operation . . . . . . . . . . . . . . . . . . . 1021 1.14.3.7.4 Request and response for the Update_Cluster_DRS_Configuration operation . . . . 1029 1.14.3.8 Adapter requests and responses for Datacenter operations . . . . . . . . . . . . . . . . . . . . . . . 1034 1.14.3.8.1 Request and response for the Retrieve_Datacenters operation . . . . . . . . . . . . . . . . 1034 1.14.3.9 Adapter requests and responses for Folder operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040 1.14.3.9.1 Request and response for the Create_Folder operation . . . . . . . . . . . . . . . . . . . . . . 1040 1.14.3.9.2 Request and response for the Retrieve_Folders operation . . . . . . . . . . . . . . . . . . . . 1042 1.14.3.9.3 Request and response for the Destroy_Folder operation . . . . . . . . . . . . . . . . . . . . . 1050 1.14.3.10 Adapter requests and responses for Discovery operations . . . . . . . . . . . . . . . . . . . . . . . 1052 1.14.3.10.1 Request and response for the Retrieve_MOB_Reference_By_Display_Name operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
13
1.14.3.10.2 Request and response for the Retrieve_Display_Name_By_MOB_Reference operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054 1.14.3.11 Adapter requests and responses for the Resource Pool operation . . . . . . . . . . . . . . . . . 1056 1.14.3.11.1 Request and response for the Retrieve_Resource_Pool_Children operation . . . . . 1056 1.14.3.12 Adapter requests and responses for the Basic vApp operations . . . . . . . . . . . . . . . . . . . 1060 1.14.3.12.1 Request and response for the Power_On_VApp operation . . . . . . . . . . . . . . . . . . . 1060 1.14.3.12.2 Request and response for the Power_Off_VApp operation . . . . . . . . . . . . . . . . . . . 1061 1.14.3.12.3 Request and response for the Unregister_VApp operation . . . . . . . . . . . . . . . . . . . 1063 1.14.3.13 Adapter requests and responses for the VApp Configuration operations . . . . . . . . . . . . 1065 1.14.3.13.1 Request and response for the Export_VApp_As_OVF_Template operation . . . . . . 1065 1.14.3.13.2 Request and response for the Import_OVF_Template_As_VApp operation . . . . . . 1067 1.14.3.13.3 Request and response for the Create VApp operation . . . . . . . . . . . . . . . . . . . . . . 1070 1.14.3.13.4 Request and response for the Clone_VApp operation . . . . . . . . . . . . . . . . . . . . . . 1073 1.14.3.13.5 Request and response for the Update_VApp_Configuration operation . . . . . . . . . . 1078 1.14.4 Monitor adapter events for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082 1.14.4.1 Event monitor adapter for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082 1.14.4.1.1 Supported event types for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082 1.14.4.1.2 Event monitor adapter events for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . 1083 1.14.4.2 SNMP monitor adapter for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086 1.14.4.2.1 SNMP monitor adapter event for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . 1086 1.14.5 Adapter request elements for VMware Infrastructure adapter . . . . . . . . . . . . . . . . . . . . . . . . . . 1090 1.14.5.1 Guest operating system identifiers for VMware Infrastructure . . . . . . . . . . . . . . . . . . . . . . 1090 1.14.5.2 spec for vApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 1.14.5.3 property-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095 1.14.5.4 product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096 1.14.5.5 ovf-section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097 1.14.5.6 ip-assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098 1.14.5.7 address-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098 1.14.5.8 console-ip-route-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099 1.14.5.9 device-change-list for removing devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099 1.14.5.9.1 Removing a hard disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099 1.14.5.9.2 Removing a CD ROM drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100 1.14.5.9.3 Removing an ethernet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100 1.14.5.10 device-change-list for updating devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101 1.14.5.10.1 Updating a SCSI controller configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101 1.14.5.10.2 Updating an ethernet adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101 1.14.5.11 ip-route-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102 1.14.5.12 cpu-feature-mask-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102 1.14.5.13 cpu-allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103 1.14.5.14 console-vnic-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105 1.14.5.15 device-change-list for adding devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106 1.14.5.15.1 Adding a SCSI controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106 1.14.5.15.2 Adding a virtual disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107 1.14.5.15.3 Adding a PCI Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108 1.14.5.15.4 Adding an ethernet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108 1.14.5.15.5 Adding a CD ROM drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109 1.14.5.16 location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110 1.14.5.17 spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111 1.14.5.18 vnic-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112 1.14.5.19 network-shaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113 1.14.5.20 vswitch-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114 1.14.5.21 entity-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117 1.14.5.22 customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119 1.14.5.23 search-domain-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122 1.14.5.24 portgroup-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123 1.14.5.25 memory-allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127 1.14.5.26 connectable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128 1.14.5.27 tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128 1.14.5.28 power-op-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
14
1.14.5.29 console-preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.14.5.30 flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.14.6 Adding an SSL certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.14.6.1 Adding an SSL certificate to the peer keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.15 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.15.1 Generic adapter troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.15.1.1 Adapter troubleshooting steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.15.1.2 Debug-level adapter logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.16 Known issues and workarounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.17 Customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.17.1 Support website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.17.2 Support by telephone or e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.18 Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1130 1131 1132 1132 1132 1132 1132 1133 1134 1138 1138 1138 1139
15
Home
This wiki space contains information about the BMC Atrium Orchestrator 20.11.02 Content release. Specifically, this wiki space applies to the application adapters.
Featured content
Hotfix and workaround available for application adapter for BMC BladeLogic Server Automation. New adapters added in the 20.11.02 release: BMC Atrium Orchestrator Application Adapter for Dell Advanced Infrastructure Manager BMC Atrium Orchestrator Application Adapter for Amazon S3 BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
Where to start
To View information about the latest service pack or release Install application adapters See What's new Installing
Configure an adapter, for example, Amazon Configuring the BMC Atrium Orchestrator Application Adapter for S3 Amazon S3 Enable an adapter Import a module Export an adapter module Activate a module Troubleshoot generic adapter issues Enabling an adapter on a peer Importing a module from the repository to BMC Atrium Orchestrator Development Studio Exporting the adapter module to the repository Activating a module on the grid manager Adapter troubleshooting steps
About BMC Atrium Orchestrator adapters

Adapters provide an interface between BMC Atrium Orchestrator workflow processes and external third-party applications and support systems. Adapters are located on peers and configured in Grid Manager to establish connections and facilitate communications. Adapters are used in BMC Atrium Orchestrator Development Studio when creating processes and in BMC Atrium Orchestrator for executing processes and providing input for rules to evaluate. Adapters are of the following categories: Base adapters interface to systems by using standard protocols, such as JDBC, Telnet, SSH, JMS processes, and so on. Application adapters interface with a specific product.
16
PDFs
Help
Recently updated pages
PDFs updated about 12 hours ago (view change) Home updated about 12 hours ago (view change) Introducing the BMC Atrium Orchestrator Application Adapter for DELL Advanced Infrastructure Manager updated about 13 hours ago (view change) More
What's new
This section provides information about what is new or changed in this space, including documentation updates, corrected issues, and enhancements. It also provides license entitlement information for the release. Placing a watch on this page is a great way to stay informed of changes to this space. The following updates have been added since the release of the space: Date August 25, 2011 Title BladeLogic adapter fails to start when configured to use the CLI tunnel interface Summary Workaround and hotfix available for defect (ADAPTER-5102)
December Documentation updates for 12, 2011 December 12, 2011
Updated the following information for the BMC Atrium Orchestrator Application Adapter for BEM and BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager: Conceptual information about the actor and monitor adapters Configuring the actor and monitor adapters Setting up events for the monitor adapter Configuring the modules
License entitlements for BMC Atrium Orchestrator Application Adapters Version 20.11.02 Documentation updates Product alerts
License entitlements for BMC Atrium Orchestrator Application Adapters

17
This page contains the license entitlements for BMC Atrium Orchestrator Application Adapters.
BMC Atrium Orchestrator - Adapter License Add-on

Includes enterprise-wide license rights to deploy one unique Application Adapter or Base Adapter for every unit licensed. Also includes unlimited deployment rights to use Light Weight Activity Peers (LAPs) [LAP = Slave peers/servers that can optionally be added to a grid to provide to accommodate network latencies and/or security topologies, and do not directly add incremental processing power] in combination with licensed adapters]. Test and development license are provided at no additional cost.
BMC Atrium Orchestrator Application Adapters

Includes enterprise-wide license rights to deploy one unique Application Adapter for every unit licensed. Application adapters are pre-developed, out-of-the-box system interfaces/gateways/connectors used to talk to non-BMC, vendor-specific applications (e.g., HP Storage Essentials, Microsoft Active Directory, VMware Virtual Infrastructure, etc.). Test and development license are provided at no additional cost.
BMC Atrium Orchestrator for Network Automation - Application Adapters

Includes enterprise-wide license rights to deploy one unique Application Adapter for the number of network devices licensed. Application adapters are pre-developed, out-of-the-box system interfaces/gateways/connectors used to talk to non-BMC, vendor-specific applications (e.g., HP Storage Essentials, Microsoft Active Directory, VMware Virtual Infrastructure, etc.). Test and development license are provided at no additional cost.
BMC Atrium Orchestrator for Server Automation - Application Adapters

Includes enterprise-wide license rights to deploy one unique Application Adapter for the number of servers licensed. Application adapters are pre-developed, out-of-the-box system interfaces/gateways/connectors used to talk to non-BMC, vendor-specific applications (e.g., HP Storage Essentials, Microsoft Active Directory, etc.). Test and development license are provided at no additional cost.
Version 20.11.02
BMC Software is releasing version 20.11.02 of the BMC Atrium Orchestrator Content. This release includes changes to base and application adapters and run books only, and not the platform. BMC Atrium Orchestrator Content version 20.11.02 is certified with BMC Atrium Orchestrator platform version 7.6.02.00 and later. This document provides information about corrected problems and known issues in this release. Note Before you install the product, check the Customer Support website at http://www.bmc.com/support for: Updated documentation (for example, flashes and technical bulletins) Product downloads, patches, and fixes Product availability and compatibility (PAC) data
Enhancements in version 20.11.02
18
This section lists the application adapters that are new or enhanced in the 20.11.02 release. The following topics are discussed: Introducing the BMC Atrium Orchestrator Application Adapter for DELL Advanced Infrastructure Manager Introducing the BMC Atrium Orchestrator Application Adapter for Amazon S3 Introducing the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager Changes to BMC Atrium Orchestrator Application Adapter for VMware Infrastructure Changes to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation Changes to BMC Atrium Orchestrator Application Adapter for Amazon EC2 Changes to BMC Atrium Orchestrator Application Adapter for HP Operations Manager Changes to BMC Atrium Orchestrator Application Adapter for HP Service Manager Changes to BMC Atrium Orchestrator Application Adapters for HP AssetCenter, HP ServiceCenter, NetApp Rapid Cloning Utility, VMware vCloud, BMC BladeLogic Network Automation, and VMware Infrastructure Changes to BMC Atrium Orchestrator Application Adapter for Service-now Changes to BMC Atrium Orchestrator Application Adapter for Microsoft Active Directory
Introducing the BMC Atrium Orchestrator Application Adapter for DELL Advanced Infrastructure Manager
The BMC Atrium Orchestrator application adapter for Dell Advanced Infrastructure Manager (AIM) consists of an actor and a monitor adapter. The actor adapter executes operations on the Dell Advanced Infrastructure Manager application by using its web services API. The monitor adapter receives SNMP traps sent by the Dell Advanced Infrastructure Manager application when events occur. On receiving the traps, the adapter creates corresponding events in BMC Atrium Orchestrator which are then used by workflows. The actor adapter supports the following categories of operations: Persona Server VMRack For more information about the BMC Atrium Orchestrator application adapter for Dell Advanced Infrastructure Manager, see PDF product guides.
Introducing the BMC Atrium Orchestrator Application Adapter for Amazon S3

The BMC Atrium Orchestrator Application Adapter for Amazon S3 consists of an actor adapter. The actor adapter executes operations on the Amazon S3 application by using the web service API. To execute the operations, the adapter invokes web service calls on the Amazon S3 server. The actor adapter supports the following categories of operations: Bucket Service Object For more information about the BMC Atrium Orchestrator Application Adapter for Amazon S3, see BMC Atrium Orchestrator Application Adapter for Amazon S3.
Introducing the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The BMC Atrium Orchestrator application adapter for BMC ProactiveNet Performance Manager is the long term replacement for the BMC Atrium Orchestrator application adapter for BMC Event Manager. BMC ProactiveNet Performance Manager is a suite of monitoring and event management solutions and this adapter integrates with the event management component to provide a bi-directional event integration.
19
For details about the adapter, see BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager.
Changes to BMC Atrium Orchestrator Application Adapter for VMware Infrastructure

This section describes the enhancements for the VMware Infrastructure adapter. For more information about these enhancements, see BMC Atrium Orchestrator Application Adapter for VMware Infrastructure.
New elements for the Event monitor adapter
A new element, <VirtualCenter>, is added for every generated event by the VMware Infrastructure event monitor adapter. The <VirtualCenter> element identifies the virtual center from where the event is generated. Another element, <uuid>, is returned for every virtual machine event generated by the event monitor adapter. This element is part of the <vm> element.
New operation for the actor adapter
The VMware Infrastructure actor adapter now supports the Update_Cluster_DRS_Configuration operation. This operation allows you to update the Cluster DRS (Distributed Resource Scheduler) configuration. In addition, you can also use this operation to manage DRS settings at the virtual machine level.
Support for additional controllers
The VMware Infrastructure actor adapter adds support for LSI Logic SAS controllers and Para virtual SCSI controllers.
Changes to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation
This section describes the enhancements for the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation. For more information about these enhancements, see BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation.
Firewall Service operations
The BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation now supports the following Firewall Service operations: Get All Firewall Rules Overwrite Firewall Rules
Application version support
The adapter now also supports BMC BladeLogic Network Automation version 8.1.01. The following table maps the Version directory information with the BMC BladeLogic Network Automation versions. Mapping of version directory information with BMC BladeLogic Network Automation application versions Version Compatible with directory application version 5.2? v5.2 v5.3 Yes No Compatible with application version 5.3? Yes Yes Compatible with application version 5.4? Yes Yes Compatible with application version 8.1? Yes Yes Compatible with application version 8.1.01? Yes Yes
20
v5.4
No
No
Yes
Yes
Yes
Changes to BMC Atrium Orchestrator Application Adapter for Amazon EC2

The BMC Atrium Orchestrator Application Adapter for Amazon EC2 now supports the updated WSDL http://ec2.amazonaws.com/doc/2009-11-30/. Support for http://ec2.amazonaws.com/doc/2009-11-30/AmazonEC2.wsdl, the older WSDL URL has been discontinued. Also, the adapter is now certified with the new WSDL, http://ec2.amazonaws.com/doc/2011-02-28/. For more information about the support for WSDLs, see BMC Atrium Orchestrator Application Adapter for Amazon EC2 .
Changes to BMC Atrium Orchestrator Application Adapter for HP Operations Manager

If the <soap-url> element specifies a secure URL (https), the value of the <use-sslcertificate> element should be set to true. If the target server certificate has expired, set the value of the <allow-unsigned-certificate> element to true and set the value of the <install-certificate> element to false to execute the request successfully. The description for the <use-ssl-certificate> configuration element has been updated in the BMC Atrium Orchestrator Application Adapter for HP Operations Manager User Guide. Also, the following elements have been added to the monitor adapter configuration: <use-ssl-certificate> <allow-unsigned-certificate> <install-certificate> <passphrase> For details about the enhancements, see PDF product guides.
Changes to BMC Atrium Orchestrator Application Adapter for HP Service Manager

The BMC Atrium Orchestrator application adapter for HP Service Manager now also supports the following versions of HP Service Manager: 7.1 7.11 9.2 If the target server certificate has expired, set the value of the <allow-unsigned-certificate> element to true and set the value of the <install-certificate> element to false to execute the request successfully. Also, if the <soap-url> element specifies a secure URL (https), the value of the <use-sslcertificate> element should be set to true. The description for the <use-ssl-certificate> configuration element has been updated in the BMC Atrium Orchestrator Application Adapter for HP Service Manager User Guide. For details about the enhancements, see PDF product guides.
Changes to BMC Atrium Orchestrator Application Adapters for HP AssetCenter, HP ServiceCenter, NetApp Rapid Cloning Utility, VMware vCloud, BMC BladeLogic Network Automation, and VMware Infrastructure
21
If the target server certificate has expired, set the value of the <allow-unsigned-certificate> element to true and set the value of the <install-certificate> element to false to execute the request successfully. If the <soap-url> element specifies a secure URL (https), the value of the <use-sslcertificate> element should be set to true. The description for the <use-ssl-certificate> configuration element has been updated in the following guides: BMC Atrium Orchestrator Application Adapter for HP AssetCenter User Guide BMC Atrium Orchestrator Application Adapter for HP ServiceCenter User Guide BMC Atrium Orchestrator Application Adapter for NetApp Rapid Cloning Utility User Guide BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation User Guide BMC Atrium Orchestrator Application Adapter for VMware Infrastructure User Guide If the <vcloud-api-url> element specifies a secure URL (https), the value of the <use-sslcertificate> element should be set to true in the BMC Atrium Orchestrator application adapter for VMware vCloud. For more information about the changes in the configuration element descriptions, see PDFs.
Changes to BMC Atrium Orchestrator Application Adapter for Service-now

The following elements have been added to the BMC Atrium Orchestrator actor adapter for Service-Now configuration: <allow-unsigned-certificates> <install-certificate> <passphrase> Also, the Troubleshooting section in the BMC Atrium Orchestrator Application Adapter for Service-now User Guide has been updated to include information about an error message. For details about the enhancements, see PDF product guides.
Changes to BMC Atrium Orchestrator Application Adapter for Microsoft Active Directory
The BMC Atrium Orchestrator Application Adapter for Microsoft Active Directory now also supports Microsoft Windows 2008 R2. For more information about this enhancement, see PDF product guides.
Corrected problems in version 20.11.02

The following problems were reported earlier and were corrected in this version. Corrected problems in 20.11.02 content release Support Tracking ID ID None Description
ADAPTER-1394 For the BMC Atrium Orchestrator Application Adapter for Amazon EC2, the describe-instances operation response did not return the architecture of the launched AMI. This issue has been corrected with the new WSDL: http://ec2.amazonaws.com/doc/2011-02-28/. ADAPTER-3015 For the BMC Atrium Orchestrator Application Adapter for Solaris Zones, the valid values in the description for the Preferred PK Algorithm field were ssh-dss and ssh-rsa instead of ssh Dss and ssh Rsa.
None
22
Documentation updates
This section contains information about documentation updates for BMC Atrium Orchestrator content 20.11.02 that are not tied to service packs and patches. Documentation updates for December 12, 2011
Documentation updates for December 12, 2011

The topics under the following section were updated on December 12, 2011: BMC Atrium Orchestrator actor adapter for BMC Event Manager Configuring the BMC Atrium Orchestrator Application Adapter for BEM BMC Atrium Orchestrator Monitor Adapter for BEM Setting up events for the BMC Atrium Orchestrator Monitor Adapter for BEM Module configuration for BMC Event Manager Propagation rules for the maintenance mode for the BMC Atrium Orchestrator Monitor Adapter for BEM BMC Atrium Orchestrator actor adapter for BMC ProactiveNet Performance Manager Configuring the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager Setting up events for the BMC Atrium Orchestrator Monitor Adapter for the BMC ProactiveNet Performance Manager Module configuration for BMC ProactiveNet Performance Manager Propagation rules for the maintenance mode for the BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager
Product alerts
The topics in this section contain information about documentation updates for BMC Atrium Orchestrator Application Adapters that is not tied to service packs and patches. BMC BladeLogic Server Automation adapter fails to start when configured to use the CLI tunnel interface (ADAPTER-5102)
BMC BladeLogic Server Automation adapter fails to start when configured to use the CLI tunnel interface (ADAPTER-5102)
Warning You cannot use the Web Services (CLI tunnel) interface in the 20.11.02 version of the BMC BladeLogic Server Automation adapter. The BMC BladeLogic Server Automation adapter fails to start when you configure it to use the Web Services (CLI tunnel) interface. This problem occurs because a dependent library was not properly packaged with the adapter. Permanent resolution to this problem will be provided in version 20.11.03 of the BMC BladeLogic Server Automation adapter.
Recommended action
Contact BMC Customer Support for a hotfix that you can install to resolve this problem. Until you install the hotfix for this adapter, you can use the 20.11.01 version of the BMC BladeLogic Server
23
Automation adapter. You can also use the standard CLI approach with the 20.11.02 version of the BMC BladeLogic Server Automation adapter.
Key concepts
The pages in this section provide a high-level overview of the actor and monitor adapters and the adapter module life cycle.
Adapter overview
Adapters provide an interface between BMC Atrium Orchestrator workflow processes and external third-party applications and support systems. Adapters are located on peers and configured in Grid Manager to establish connections and facilitate communications. Adapters are used in BMC Atrium Orchestrator Development Studio when creating processes and in BMC Atrium Orchestrator for executing processes and providing input for rules to evaluate. Adapters are of the following categories: Base adapters interface to systems by using standard protocols, such as JDBC, Telnet, SSH, JMS processes, and so on. Application adapters interface with a specific product. Within these categories are adapters of the following types: Actor adapters Monitor adapters
Actor adapters
Actor adapters interact with external systems, sending commands or requests and, in some cases, receiving responses to requests. For example, an email actor adapter can be used to send an email message.
24
Monitor adapters
Monitor adapters listen on external systems and, based on their configuration, generate events. An email monitor adapter would monitor an email account on a specified server and generate an event when a specific message is received. This event could be used to trigger a workflow process.
You can configure the adapters with Grid Manager for specific grids and can then enable them on one or more peers on the grid. Any adapter that is used in a process must be enabled on at least one peer on a grid. The configuration is referenced when adapters are called within processes. You can create processes within BMC Atrium Orchestrator Development Studio. Actor adapters are used within workflow processes to perform specific functions and to interface with external applications. Schedules can be created to trigger the execution of specific processes. You can create rules within BMC Atrium Orchestrator Development Studio to evaluate events generated by monitor adapters. A rule contains event criteria and specifies a process to be executed when the rule is satisfied (true). You can create a module using BMC Atrium Orchestrator Development Studio. A module contains processes, schedules, and rules. Modules are exported from BMC Atrium Orchestrator Development Studio, within snapshots, to a grid's library for deployment and activation in Grid Manager. On activation of a module on a grid, schedules and rules are enabled. Schedules trigger processes at defined intervals and rules evaluate events generated by monitor adapters, triggering designated processes for events that evaluate to true for a rule. A single event can trigger multiple processes if multiple rules evaluate to true for that event.
Adapter module lifecycle

An adapter module contains a set of processes, schedules, rules, and configurations. You can create schedules and rules to trigger process execution. Each operation supported by the application adapter has a corresponding process in the adapter module. The following figure outlines the steps required to work with an adapter module.
25
Working with Grid Manager and BMC Atrium Orchestrator Development Studio
This section provides information about using the Grid Manager and BMC Atrium Orchestrator Development Studio to work with adapters. Importing a module from the repository to BMC Atrium Orchestrator Development Studio Enabling an adapter on a peer Exporting the adapter module to the repository Activating a module on the grid manager
Importing a module from the repository to BMC Atrium Orchestrator Development Studio
To use the processes contained in this module as part of more complex workflow processes, you must import the module from the repository and unbundle it in BMC Atrium Orchestrator Development Studio.
To import a module from the repository to BMC Atrium Orchestrator Development Studio
1. Access the Library Manager view by clicking Library Manager . 2. Within the Library Manager view, click the Import modules tab. 3.
26
3. Click From Repository. 4. To display all modules in the repository, select the Show All Versions check box. Note If you are working offline, the Login window is displayed. You must log on to import a module from the repository. 5. Select the Unbundle check box for each module to import and unbundle, and then click Import. The Library Manager imports and unbundles the selected modules and the module list refreshes to show the modules that were imported. 6. To begin working with the modules, click the Process Designer icon on the tool bar to switch to the Process Designer view.
Enabling an adapter on a peer

The peers on the grid on which a process executes handle the adapter requests. Depending on the value for the peer location set in the adapter request, you might need to enable the adapter on more than one peer for processes to execute successfully. The following table describes which adapters to enable, based on the value for the peer location in the adapter request.
Enabling adapters based on peer location defined in an adapter request
Peer Description location any The adapter request can be serviced by any peer in the grid. The master job processor distributes the process to the next available peer. The peer that contains the master job processor services the adapter request.
Enable adapter on at least one peer on the grid
this
the CDP and all activity peers on the grid Note: Lightweight Activity peers cannot become the master job processor. at least one peer on the grid the peer specified in the adapter request
best Peer
The grid determines the best peer to service the request. You specify the exact peer to service the adapter request.
To enable an adapter on a peer

1. Click the Manage tab, and click the Peers tab. 2. From the currently defined peers for the selected grid, select the peer on which to enable the adapter, and then click Edit . 3. On the Edit a Peer Configuration page, click Enable to display the available adapters for this peer. 4. Select the adapter to enable, and then click OK. You can select multiple adapters by pressing the Shift or Ctrl key while selecting adapters. 5. Click OK to save the peer configuration. Labels: BMC Atrium Orchestrator Application Adapter, Task, actor adapter:enabling
Exporting the adapter module to the repository

A set of processes, schedules, rules, and configurations are contained within a module. You can export modules
27
from BMC Atrium Orchestrator Development Studio to the repository.
To export the adapter module to the repository

1. Access the Library Manager view by clicking Library Manager. 2. Within the Library Manager view, click the Export modules tab. 3. From Local Folder, select the local library from which to export the module. In the Export modules window, the modules in the BMC Atrium Orchestrator Development Studio Workspace and Local Library of the current Grid are displayed in the Export Module(s) pane. For modules that have more than one version, the module name is highlighted. You can select an earlier version of the module by selecting an option under Version. You can export more than one module, but only one version for any module. A Flag icon identifies modules that were changed after the last export. For these modules, you must use the list box under Version to specify the type of version change (Major or Minor) to apply. Major increments the version, for example, from 3.0.00 to 4.0.00. Minor increments the version, for example, from 3.0.00 to 3.1.00 4. Select the modules to export, and click Export to Repository. Ensure that you select the adapter module and any module that uses processes from this adapter module in larger workflows.
Note If you are working offline, the Login window is displayed. 5. On the Export Confirmation window, verify the information and click Proceed. When the export process is finished, the list of Export modules shows the module names and the updated version numbers. When you have finished exporting modules to the repository, select an icon on the tool bar to switch to a different view. Labels:
Activating a module on the grid manager

Activating a module on the grid triggers the schedules and rules to execute processes. Before you activate a module, you must export the relevant module to the repository.
To activate a module
1. 2. 3. 4. Log on to the Grid Manager. Click the Manage tab, and click the Modules tab. On the Modules in Repository page, select the check box corresponding to the module. Click Activate. A message stating that the module is activated successfully is displayed.
Installing
The pages in this section describe how to install BMC Atrium Orchestrator content. BMC Atrium Orchestrator content includes base and application adapters, operations actions and workflows, and run books. Operations
28
actions and workflows are groups of processes, schedules, rules, and configuration items for specific operational disciplines. The processes, schedules, rules, and configuration items are based on the IT infrastructure Library (ITIL).
Recommended installation environment

For detailed information about the compatible versions of BMC and third-party products for this version of BMC Atrium Orchestrator, see the following Product Availability and Compatibility pages: Platform Content
Related topic
BSM Interoperability and BSM Reference Stack
Installation paths
You use the content installation program to install or upgrade base adapters, application adapters, modules, and solutions. The content GUI and silent installations enable you to choose one of the following installation options: BSM Solutions, which selects and installs the content required for your solution Custom feature set, which enables you to select the content to install The installation option that you select is determined by the terms of your license.
BSM Solutions installation path

When installing BMC Atrium Orchestrator content for use with a solution, choose the BSM Solutions installation path, which preselects the content required for your solution and then installs all of the dependent adapters and modules. The installation program also verifies that you have installed the prerequisite versions of Access Manager, the repository, and other BMC products. Note When running the content installation program: A preselected and dimmed content option (such as an adapter or a module) indicates that the installation program located an existing version of the content required for the solution on your system. When you select BSM Solutions, you cannot clear this selection. A preselected option that is not dimmed indicates that the installation program located an existing version of the adapter or module on your system that is not required for the solution. Because it is not required, you can choose to not install that content by clearing the check box. For more information about installing content for BMC solutions, see the corresponding solution documentation.
Custom feature set installation path

The Custom feature set option provides a path for you to install any content. If you choose the Custom feature set option, the installation program does not preselect any content options or configure artifacts for a BSM solution.
29
Tip Unless you are installing a solution, always select this option.
Using the GUI to install BMC Atrium Orchestrator content

This procedure describes how to use the GUI installation to install content using the Custom feature set option. Note If you purchased a BSM Solution from BMC, see the corresponding solution system requirements and installation procedures for its predefined workflows. Do not use the procedures in this section to install predefined workflows.
Before you begin

You must have downloaded the content installation files from the BMC Electronic Product Distribution (EPD) website. You must have Access Manager and the repository installed and running, as described in Installing Access Manager and the repository. The computer from which you run the installation program must have network access to the repository computer.
To install BMC Atrium Orchestrator content with the GUI installation

1. Navigate to and start the installation program. Windows: windows_bao_content_installer_v_r_mm_pp.exe UNIX: Linux: linux_bao_content_installer_v_r_mm_pp.bin Solaris: solaris_bao_content_installer_v_r_mm_pp.bin 2. On the Welcome to BMC Atrium Orchestrator panel, review the information and click Next. 3. On the license agreement panel, select I agree to the terms of the license agreement; then click Next. 4. On the Directory Selection panel, accept the default location, or click Browse to select a different location; then click Next. 5. On the Installation Type panel, select Custom feature set, and click Next. Do not select BSM Solutions unless you have purchased a BMC solution and have reviewed the applicable documentation for that solution. 6. On the Repository Communications Settings panel, enter the repository settings, and click Next: Web Server Protocol: Select http. Host Name or IP Address: Enter the host name or IP address of the repository. Web Server Port Number Repository User Repository Password 7. On the Adapter Feature Selection panel, select the adapters to install, and click Next: To select all adapters, select Adapters. To select all the adapters in a group, select Base Adapters, BMC application adapters, or Third party adapters. Note If you select existing application adapters or base adapters, they will be updated to the current version when you click Install. 8.
30
8. On the Module Feature Selection panel, select the run books and management modules and core modules to install, and click Next. To select all modules, select Modules. To select all the modules in a selected group, select Run books, Management modules or Core modules. 9. On the Installation Preview panel, review the features, and then click Install. 10. When the installation is finished, click Done.
Troubleshooting
The BAO_content_install_log file contains the logs of the content installation, which you can use for troubleshooting installation problems. When you install an adapter that does not have a corresponding module, the content installation program writes the following warning message to the log file:
LOG EVENT {Description=[Source roar folder does not exist for this adapter],Detail=[Not all adapters have roar files so this may or may not be an error]}
This warning message is informational and does not indicate that a problem occurred during the installation. To troubleshoot problems that might have occurred during the installation, search for the BAO_content_install_log file for error messages.
Using command-line options to install BMC Atrium Orchestrator content

In a silent installation, you run the installation program from a command line. You can run a silent installation on Red Hat or SUSE Linux, Oracle Solaris, and Windows to install the BMC Atrium Orchestrator content. When you execute a silent installation, you specify an options file to feed the installation settings to the program. The options file is a text file that defines all the required installation properties. You create options files to install or upgrade the BMC Atrium Orchestrator platform and content. On Windows computers, the silent installation does not direct output to the console. On UNIX computers, a short startup message and a console representation of a progress meter is displayed. The installation finishes without comments on the screen.
Silent installation properties

The silent installation options file is a text file that defines the type of installation, the components to install, the installation location, and the configuration settings for the components. The installation properties are in the form of a prefix tag followed by a property name and value pair.
Prefix tags
The following table lists the prefix tags that precede the installation properties. Prefix tags for silent installation properties Property flag Description -J Precedes Java properties
31
-P
Precedes directory properties Installation properties for platform options files Installation properties for content options files
Installation properties for content options files

The table on this page lists the properties that you can include in the options file for content. The values that you assign to these properties determine the settings for the installation program. To help you determine your property values, see Sample content options file templates. When you use the silent installation to install content, the computer from which you run the installation program must have network access to the repository computer. Note If you have purchased the following solutions from BMC, see the system requirements and installation procedures for these predefined workflows. Do not use the silent installation procedures on this page to install predefined workflows. BMC Continuous Compliance for Network Automation BMC Continuous Compliance for Server Automation BMC Cloud Lifecycle Management BMC Cloud Lifecycle Management without ITSM BMC ProactiveNet Performance Management Triage and Remediation
Installation properties for content options file Property name installLocation Description and sample property Specifies the full path to the installation directory Default value: Windows: c:\Program Files\BMC Software\AO\content UNIX: /opt/bmc/ao/content -P installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES Used with the content installer, specifies to install all content for BMC Atrium Orchestrator; does not include BSM Solution workflows -J AO_INSTALLING_FEATURES=ALL To specify the group of adapters to install, use one of the following values: ALL: installs all base and application adapters BASE or base-adapters: installs all base adapters but no application adapters APP or application-adapters: installs all application adapters but no base adapters -J AO_INSTALLING_FEATURES=APP,adapter-http,adapter-jms
32
To specify the group of modules to install, use one of the following values: ALL: installs all platform and task management modules platform-modules: installs all platform modules task-management-modules: installs all task management modules but no platform modules run-book-modules: installs all run books -J AO_INSTALLING_FEATURES=platform-modules -J AO_INSTALLING_FEATURES=run-book-modules -J AO_INSTALLING_FEATURES=task-management-modules To specify selected content, type the feature names, separated by a comma. -J AO_INSTALLING_FEATURES=adapter-email,adapter-http, adapter-jms,adapter-powershell,adapter-scripting, adapter-snmp,adapter-sql,adapter-terminal, adapter-windows-command,adapter-ws For a complete list of valid features, see Sample content options file templates. AO_CONTENT_INSTALL_TYPE Specifies the types of content installed For more information about installation types, see Installing BMC Atrium Orchestrator content. INSTALL_TYPE_CUSTOM: installs any combination of content Always specify this option unless you have purchased a BMC solution that requires one of the BMC solutions that requires a predefined workflow. INSTALL_TYPE_SOLUTIONS: installs content based on predefined BSM solutions; the adapters integrate with other BMC products When you specify this option, you must also include the following properties: INSTALL_REMEDY_ITSM_INTEGRATIONS: true or false REMEDY_PORT_NUMBER: "0" for automatic port mapping, or you can use specific port number REMEDY_HOSTNAME: DNS name or IP of the target Remedy ITSM system REMEDY_USER_NAME: Remedy administrator user name REMEDY_PASSWORD: Remedy user password ITSM_AUTHORING_COMPANY: Support company name for imported templates ITSM_AUTHORING_ORGANIZATION: Support organization name for imported templates ITSM_AUTHORING_GROUP: Support group name for imported templates -J AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_CUSTOM AO_REPOSITORY_PROTOCOL AO_REPOSITORY_HOST Specifies the protocol used to access the repository -J AO_REPOSITORY_PROTOCOL=http Specifies the host name of IP address for the repository. The value cannot be a loopback address -J AO_REPOSITORY_HOST=111.11.111.111 Specifies the port to access the repository -J AO_REPOSITORY_PORT=28080
AO_REPOSITORY_PORT
AO_REPOSITORY_USER_NAME Specifies the user name required to log on -J AO_REPOSITORY_USER_NAME=admin
33
AO_REPOSITORY_PASSWORD
Specifies the password that corresponds to the user name Note: The password value is encrypted and is not stored in the installation log. -J AO_REPOSITORY_PASSWORD=myPassword
Sample content options file templates

This section contains samples that you can use to create options file for installing content with a silent installation. Note The following options file templates contain sample values that you must replace with values suitable for your environment.
Options file to install all content

The properties in the following options file install all adapters, modules, and run books.
-P -J -J -J -J -J -J -J installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES=ALL AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_CUSTOM AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Options file to install all base adapters

The properties in the following options file install all base adapters.
-P -J -J -J -J -J -J -J installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES=BASE AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_CUSTOM AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Options file to install selected base adapters

The properties in the following options file install selected base adapters. When specifying multiple adapters, comma-separate the adapter names.
34
-P installLocation=C:\Program Files\BMC Software\AO\content -J AO_INSTALLING_FEATURES=adapter-email,adapter-http,adapter-jms,adapter-powershell,adapter-script AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_CUSTOM -J AO_REPOSITORY_PROTOCOL=http -J AO_REPOSITORY_HOST=<hostNameOrIpAddress> -J AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> -J AO_REPOSITORY_USER_NAME=admin -J AO_REPOSITORY_PASSWORD=<password>
Options file to install all application adapters

The properties in the following options file install all of the available application adapters.
-P -J -J -J -J -J -J installLocation=<installationPathAndDirectory> AO_INSTALLING_FEATURES=APP AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Options file to install selected adapters

The properties in the following options file install a combination of base and application adapters.
-P installLocation=C:\Program Files\BMC Software\AO\content -J AO_INSTALLING_FEATURES=adapter-email,adapter-http,adapter-jms,adapter-snmp, adapter-windows-command,adapter-ws,adapter-active-directory, adapter-ars,adapter-bmc-atrium-cmdb -J AO_REPOSITORY_PROTOCOL=http -J AO_REPOSITORY_HOST=<hostNameOrIpAddress> -J AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> -J AO_REPOSITORY_USER_NAME=admin -J AO_REPOSITORY_PASSWORD=<password>
Options file to install all platform modules

The properties in the following options file install all of the available platform modules.
-P -J -J -J -J -J -J installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES=platform-modules AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Options file to install all task management modules
35
The properties in the following options file install all of the available platform modules.
-P -J -J -J -J -J -J installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES=task-management-modules AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Options file to install selected modules

The properties in the following options file install specific modules.
-P installLocation=C:\Program Files\BMC Software\AO\content -J AO_INSTALLING_FEATURES=AutoPilot-AD-Utilities,AutoPilot-OA-Applications_Utilities,AutoPilot-OAAO_REPOSITORY_PROTOCOL=http -J AO_REPOSITORY_HOST=<hostNameOrIpAddress> -J AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> -J AO_REPOSITORY_USER_NAME=admin -J AO_REPOSITORY_PASSWORD=<password>
Options file to install all run books

The properties in the following options file install all run books.
-P -J -J -J -J -J -J installLocation=C:\Program Files\BMC Software\AO\content AO_INSTALLING_FEATURES=run-book-modules AO_REPOSITORY_PROTOCOL=http AO_REPOSITORY_HOST=<hostNameOrIpAddress> AO_REPOSITORY_PORT=<portNumberOnRepositoryServer> AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD=<password>
Installable feature list

When specifying specific features with the AO_INSTALLING_FEATURES property, refer to the list of feature names in the following table that you can use in the options file. Installable product names and feature names Feature type and installable feature name Product name Base adapters adapter-email adapter-http adapter-jms eMail HTTP JMS
36
adapter-powershell adapter-scripting adapter-snmp adapter-sql adapter-terminal adapter-windows-command adapter-ws BMC application adapters adapter-ars adapter-bmc-atrium-cmdb adapter-bbna adapter-bppm adapter-bem adapter-bladelogic-server-automation adapter-bpm Third-party adapters adapter-amazon-ec2 adapter-amazon-s3 adapter-dell-aim adapter-hp-asset-center adapter-netapp-storage adapter-hp-nnm adapter-hp-operations-manager-unix adapter-hp-operations-manager-windows adapter-hp-servicecenter adapter-hp-service-desk adapter-hp-servicemanager adapter-hp-storage-essentials adapter-omnibus adapter-ibm-tsm adapter-active-directory adapter-microsoft-exchange adapter-microsoft-exchange-v2003 adapter-ms-sccm
Microsoft Windows Powershell Scripting SNMP SQL Terminal Windows Command Line Web Services
BMC Remedy Action Request System (ARS) BMC Atrium CMDB BMC BladeLogic Network Automation BMC ProactiveNet Performance Manager BMC Event Manager and ProactiveNet BMC BladeLogic Server Automation BMC Performance Manager Portal
Amazon Elastic Compute Cloud Amazon S3 Dell Advanced Infrastructure Manager HP Asset Center Netapp Storage HP Network Node Manager (NNM) HP Operations Manager for Unix HP Operations Manager for Windows HP Service Center HP Service Desk HP Service Manager HP Storage Essentials IBM (Micromuse) Tivoli Netcool OMNIbus IBM Tivoli Storage Manager Microsoft Active Directory Microsoft Exchange Microsoft Exchange v2003 Microsoft System Center Configuration Manager
37
adapter-mom adapter-netapp-rcu adapter-ms-sccm adapter-service-now adapter-solaris-zones adapter-vmware-infrastructure adapter-vmware-lcm adapter-vmware-vcloud Run books Server_Instance-SA-Placement_Engine Closed_Loop-SA-Change_Management Virtualization-SA-Management NetApp-SA-Solutions Triage-SA-and_Remediation Server-Continuous-Compliance BladeLogic-SA-ITSM_Integration Closed_Loop_Server-SA-Audit Closed_Loop_Server-SA-Compliance Server_Incident-SA-Enrichment Management modules AutoPilot-OA-Change_Management AutoPilot-OA-Configuration_Management AutoPilot-OA-Configuration_Utility AutoPilot-OA-Credentials_Store AutoPilot-OA-Event_Management AutoPilot-OA-Incident_Management AutoPilot-OA-Problem_Management AutoPilot-OA-Storage_Management AutoPilot-OA-Task_Management AutoPilot-OA-Virtual_Server_Management Core modules AutoPilot-AD-Utilities AutoPilot-OA-Applications_Utilities AutoPilot-OA-Common_Utilities
Microsoft Operations Manager NetApp Rapid Cloning Utility Microsoft System Center Operations Manager Service-now Solaris Zones VMware Infrastructure VMware Lifecycle Manager VMware VCloud
Server Instance SA Placement Engine Continuous compliance for Network Discovery Synchronization NetApp Solutions Triage and Remediation Continuous compliance for Server BladeLogic ITSM Integration Closed Loop Server Audit Closed Loop Server Compliance Server Incident Enrichment
AutoPilot OA Change Management AutoPilot OA Configuration Management AutoPilot OA Configuration Utilities AutoPilot OA Credentials Store AutoPilot OA Event Management AutoPilot OA Incident Management AutoPilot OA Problem Management AutoPilot OA Storage Management AutoPilot OA Task Management AutoPilot OA Virtual Server Management
AutoPilot OA Base Adapter Utilities AutoPilot OA Applications Utilities AutoPilot OA Common Utilities
38
AutoPilot-OA-Directory_Services_Utilities AutoPilot-OA-File_Utilities AutoPilot-OA-Network_Utilities AutoPilot-OA-Operating_System_Utilities AutoPilot-OA-Physical_Device_Utilities
AutoPilot OA Directory Services Utilities AutoPilot OA File Utilities AutoPilot OA Network Utilities AutoPilot OA Operating System Utilities AutoPilot OA Physical Device Utilities
Installable solutions
When you specify INSTALL_TYPE_SOLUTIONS as the AO_CONTENT_INSTALL_TYPE property, you can specify one of the options in the following table in the options file. Before you create an options file to install a solution, refer to the installation or getting started documentation for the solution. Installable solutions names and feature names BSM solution name BMC Continuous Compliance for Networks BMC Continuous Compliance for Servers BMC Triage and Remediation BMC Cloud Lifecycle Management Content feature name ContinuousComplianceNetworks ContinuousComplianceServers TriageAndRemediation VirtualLifeCycleManagement
BMC Cloud Lifecycle Management without ITSM VirtualLifeCycleManagementNoItsm
Creating an options file

You must create an options file for each silent installation that you want to perform. The procedure on this page describes how to create options files for BMC Atrium Orchestrator content. You can create an options file that installs multiple types of content or a single content type. Best practice To create options files, copy and modify the options file templates in Sample content options file templates. Whenever you run a GUI installation, the installation program creates an options file in the top level of the installation directory. You can use these files as templates to create a new installation options file.
Before you begin

Locate the sample files that you can leverage to create options files for your installation scenario.
To create an options file for BMC Atrium Orchestrator content

1. Open a text editor to create a new options file. 2. Copy the content from a content template options file into the new file. 3.
39
BMC Atrium Orchestrator Application Adapters 20.11.02 2. 3. In the new file, modify the installLocation property and specify an existing directory in which to install the component. The installation directory must have network access to the repository. Example -P installLocation=c:\Program Files\BMC Software\AO\content
4. For the AO_CONTENT_INSTALL_TYPE property, specify INSTALL_TYPE_CUSTOM. -J AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_CUSTOM 5. For the AO_INSTALLING_FEATURES property, specify the content features to install. Note For more information about specifying content features, see Sample content options file templates and Silent installation properties.
6. Specify the repository communication features. 7. Save the file with a name that indicates the purpose of the installation. For example, you could name the options file bao_content.options. Note UNIX operating systems are case-sensitive. Do not mix upper- and lowercase characters when you name files for a UNIX environment.
Where to go from here

Run the installation from a command line, as described in Executing a silent installation.
Executing a silent installation

Regardless of the content, you use the same command to launch the installation program in silent mode. The options file determines the content to install. You launch the silent installation from the command line and are not prompted for input. When typing the command, replace v_r_mm_pp with 20_11_02_00.
Before you begin

You must have downloaded the installation files from the BMC EPD website. You must have created the necessary options files. You must have installed the repository. On Red Hat Linux or Oracle Solaris operating systems, you can output debug logging to the console window by exporting LAX_DEBUG=true.
To execute a silent installation

40
1. On a computer that has network access to the repository, navigate to the directory that contains the installation program. 2. From the command line, execute one of the following commands to start the installation program in silent mode. When you specify the options file name, specify the full path to the options file; do not specify a path that is relative to the installation program. Platform Command Linux Solaris sh ./linux_bao_content_installer_v_r_mm_pp.bin -i silent -DOPTIONS_FILE="fullPathToOptionsFile/optionsFile" sh ./solaris_bao_content_installer_v_r_mm_pp.bin -i silent -DOPTIONS_FILE="fullPathToOptionsFile/optionsFile"
Windows pathToInstaller\windows_bao_content_installer_v_r_mm_pp.exe -i silent -DOPTIONS_FILE="fullPathToOptionsFile\optionsFile"
Type the command carefully. If you type the command incorrectly, you might invoke an installation mode that is unsupported.
Where to go from here

To confirm that the installation is finished, view the installation log files.
BMC Atrium Orchestrator Application Adapter for Amazon EC2

Amazon Elastic Compute Cloud (Amazon EC2) is a web service that enables you to launch and manage server instances in Amazon data centers. The BMC Atrium Orchestrator Application Adapter for Amazon Elastic Compute Cloud provides the interface between the workflow processes and Amazon EC2. The application adapter for Amazon EC2 contains an actor adapter and an adapter module, which comprise workflow processes that perform the standard application actions available through the Amazon EC2 web services. The actor adapter enables you to perform the following categories of operations in Amazon EC2: Amazon Machine Image operations Instance operations Key pair operations Monitoring operations Security Group operations Utility operations Windows operations Regions and Availability Zones operations Elastic Block Store (EBS) operations Elastic IP addresses operations
Peer synchronization required

The BMC Atrium Orchestrator peer on which the adapter is enabled must have correct clock settings because the Amazon Web Service uses timestamp security in SOAP requests. SOAP requests are valid only for a specific time frame to avoid replay attacks. A SOAP request's validity is also controlled by the time-to-live adapter configuration parameter, which, if set to 60, means that the request is valid for one minute only from the current time
41
on the peer. However, if the clock settings on the peer are not in sync with the standard time server, you might receive an error response with the Request has expired message.
Configuring the BMC Atrium Orchestrator Application Adapter for Amazon EC2 adapter
While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. Note Before creating an adapter configuration, ensure that the prerequisites are met. The default name for the actor adapter is AmazonEC2ActorAdapter.
To configure the actor adapter

1. To access the adapters page, click the Manage tab, then click the Adapters tab. 2. Click Add. 3. On the Add an Adapter Configuration page, specify the properties for the new Adapter, and click OK. a. Type a description for the adapter. b. In Type, select the bmc-adapter-amazon-ec2-actor versionNumber as the adapter type. c. In Properties, specify the adapter configuration properties in an XML format, including all required elements, indicated in the following table. If the default value for an optional element is acceptable, omit the element. Do not include empty elements. To resolve proxy settings errors, enter the proxy settings for the Internet connection. To resolve authentication errors, enter a valid user name and password. XML sample for configuring the actor adapter without any configuration elements
<config/>
XML sample for configuring the actor adapter with the key-files mode
42
<config> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/ </wsdl-location> <endpoint-address>http://eu-west-1.ec2.amazonaws.com/ </endpoint-address> <time-to-live>60</time-to-live> <signature-properties mode = "key-files"> <private-key-file>C:\Security\pk-MJ5GIUNLM2XJ3VRJSY TKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\cert-MJ5GIUNLM2XJ3VRJS YTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <proxy-settings> <host>10.10.75.120</host> <port>3128</port> <user-name>jones</user-name> <password>bmc1234</password> </proxy-settings> </config>
XML sample for configuring the adapter with the key-data mode
43
<config> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/ </wsdl-location> <endpoint-address>http://eu-west-1.ec2.amazonaws.com/ </endpoint-address> <time-to-live>60</time-to-live> <signature-properties mode = "key-data"> <private-key-data>-----BEGIN PRIVATE KEY----MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAA oGBAKomKro6VbW4PeQtUhNzZpSH26vbBTBtH1r4EjnIv4vnhSyyA62ewp ROVNn0SpvjoBFwE88HcX3tXym/zbVgtdPke9K+SYHP6CWdiLqnkzXde +e3GX/y+OIRlFvA1FKgpHKF+a0nVMdwxpxPzJqwFSEKgMaqSo73f0HZOY8PN4y9 AgMBAAECgYAtUd0vnToXHOvfSvMBm0tHZKhuLfhD3czsPgccvQvIB/LA5Ol15UOO nQ6cvyTgQNDx1BhynFjuYbtnM19nYEsNpR8Ndxfv7dSAcqZVHsu8OfShQ/WoRqU5 ZxSHyVGLrteIKjuv/cy/ac2clqlJu6arzc2JquiDZQ9KbEY4ODtPQQJBNC+rSrEP qHbWp0URMdzjiskO3c4amiyoIlWO4F0GnWHjn/WnjUdVQ9mZrNTter7qUtZEyq839 B6iQ8WHvfU0meMCQQC1vjDoTqEuxFHkc6qBdrjXK6Rqp23smX0mHLqKnjxlbD8t8n ki65wh5UY8mpoe6t9Ehcnghouhcnhko2/6/IDfAkBP5BNzzjpj0s3TUhYDAb6DovcA +xElja5UQto7aDcSKGRr6LxJaPzDDlz0ZW0jMs0GK8w8eDRh+ckJkWQa1rvtAkAkhPgs 5gfrbtWJ01gytZmE2ycpq0UiYuFL9D/jtNIsCylS4UNIKhHwmbKYYPSRO97rVPrw2/ hY07iveEv7Ihv/AkAaIoKFbuJhln+tlJdmN16mzl1QnyDi469i2C/yXQEvNkjiDQGHr MlhA+0eik8+JuL/TEwgrcOYKP5BI0XNL71L -----END PRIVATE KEY-----</private-key-data> <certificate-data>-----BEGIN CERTIFICATE----MIICdzCCAeCgAwIBAgIFXseN2xbnDQYJKoZIhvcNAQEFBQAwUzELMAkGA1UEBhMC VVMxEzARBgNVBAoTCkFtYXpvbi5jb20xDDAKBgNVBAsTA0FXUzEhMB8GA1UEAxMY QVdTIExpbWl0ZWQtQXNzdXJhbmNlIENBMB4XDTA5MTExMzA3MDYyMVoXDTEwMTEx MzA3MDYyMVowUzELMAkGA1UEBhMCVVMxEzARBgNVBAoTCkFtYXpvbi5jb20xFzAV BgNVBAsTDkFXUy1EZXZlbG9wZXJzMRYwFAYDVQQDEw0xeHVidzR2NmRrY2xlMIGf MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqJiq6OlW1uD3kLVITc2aUh9ur2wUw bR9a+BI5yL+L54UssgOtnsKUTlTZ9Eqb46ARcBPPB3F97V8pv821YLXT5HvSvkmB z+glnYi6p5M13Xvntxl/8vjiEZRbwNRSoKRyhfmtJ1THcMacT8yasBUhCoDGqkqO 939B2TmPDzeMvQIDAQABo1cwVTAOBgNVHQ8BAf8EBAMCBaAwFgYDVR0lAQH/BAww CgYIKwYBBQUHAwIwDAYDVR0TAQH/BAIwADAdBgNVHQ4EFgQUkm3B1OqNA7E6ZWew RC7GMGfoFd8wDQYJKoZIhvcNAQEFBQADgYEABzTAe7dUsEfR1fGsgHjAt0vhqwAx +S/V5tLZZXjsnuW6jowOyHqZrZ/9xZlWrK6wfmHoHUBNkMc935EuCiAH0qX6oef/ m/0iDplDR7XkyTxAx0AWo0RF4mstOszPGbpHBKFri2qxyXM0NmIPX2dJqhKICXP4 8HATrUjWl+peSog= -----END CERTIFICATE-----</certificate-data> </signature-properties> <proxy-settings> <host>10.10.75.120</host> <port>3128</port> <user-name>jones</user-name> <password>bmc1234</password> </proxy-settings> </config>
The following table shows the configuration elements for the actor adapter. Node elements required for configuring the actor adapter Element Description Required
44
<wsdl-location>>
Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/
Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions The values for the different regions are: http://us-east-1.ec2.amazonaws.com/: Endpoint in the US East region (Northern Virginia) http://us-west-1.ec2.amazonaws.com: Endpoint in the US West region (Northern California) http://eu-west-1.ec2.amazonaws.com/ : Endpoint in the European region (Ireland) Default value: US East region: http://us-east-1.ec2.amazonaws.com/
<time-to-live>
Specifies the time (in seconds) for which the adapter request is signed as valid Default value: 60 seconds
No
<signature-properties> Specifies the mode for signing the adapter request Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data>
45
<private-key-file>
Specifies the path for the private key file
Conditional; required if <signature-properties mode = "key-files"> Conditional; required if <signature-properties mode = "key-files"> Conditional; required if <signature-properties mode = "key-data"> Conditional; required if <signature-properties mode = "key-data"> No
<certificate-file>
Specifies the path for the certificate file
<private-key-data>
Contains the data in the private key file
<certificate-data>
Contains the data in the certificate file
<proxy-settings>
Contains the elements that define the HTTP proxy settings If you specify this element, you must also specify the <host> and <port> elements. You must specify the <user-name> and <password> elements only if the proxy server requires this authentication. Specifies the host name or the IP address of the destination host for the adapter request Specifies the destination port for the adapter request Specifies the name of the user on the specified host You must specify this element only if the proxy server requires this authentication. Specifies the password for the user on the specified host You must specify this element only if the proxy server requires this authentication.
<host> <port> <user-name>
Conditional; required if <proxy-settings> is specified Conditional; required if <proxy-settings> is specified Conditional; required if <proxy-settings> is specified
<password>
Conditional; required if <proxy-settings> is specified
BMC Atrium Orchestrator Application Adapter for Amazon EC2 module

Each command supported by the application adapter has a corresponding process in the adapter module. Top-level processes perform high-level functions and call specialized processes in subdirectories. Each subdirectory contains process directories that correspond to the operation type for that command.
Top-level processes for the BMC Atrium Orchestrator Application Adapter for Amazon EC2
The top-level processes perform high-level functions and call specialized processes in the subdirectories of the v1.0 directory. The top-level processes in the Project Explorer window execute the following version-specific Amazon EC2 processes: Create Items Delete Items Find Items
46
Perform Operations Update Items
The following table describes the elements for the top-level processes: Elements for the top-level processes Element <adapter name> <version> <wsdl location> <endpoint address> Definition Specifies the name of the adapter Specifies the current supported version, v1.0 Specifies the target WSDL URL for Amazon EC2 The value of <wsdl location> specified in the adapter request overrides the WSDL URL specified in the adapter configuration. Required No Yes No
Specifies the relevant Amazon Web Service endpoint for performing operations on No Amazon EC2 instances across different regions The value of <endpoint address> specified in the adapter request overrides the value specified in the adapter configuration. Specifies the mode for signing the adapter request The value of <signature properties> specified in the adapter request, overrides the value specified in the adapter configuration. Specifies the relevant item type for the process to be executed For more information, see Mapping between processes and operation names. Contains the <items> XML used to perform an operation in Amazon EC2 No
<signature properties> <item type> <items>
Yes Yes
Setup_Validation directory for BMC Atrium Orchestrator Application Adapter for Amazon EC2 directory
The processes in the Setup_Validation directory contain sample values for the request elements. You can change these sample values quickly to reflect the values in your environment. A process is provided to test each supported method of executing operations in Amazon EC2.
Utilities directory for the BMC Atrium Orchestrator Application Adapter for Amazon EC2
The Utilities directory contains helper and constructor processes that create the XML inputs used in functional processes. The functional processes require complex XML inputs. You can generate these complex XML inputs using the constructor processes in the Utilities directory.
v1.0 directory for the BMC Atrium Orchestrator Application Adapter for Amazon EC2
The v1.0 directory contains functional processes specific to Amazon EC2. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of the operation. The following table shows the mapping between processes and operation names.
47
Mapping between processes and operation names Process name Amazon Machine Image operation Create Image Describe Images Register Image Deregister Image Describe Image Attribute Modify Image Attribute Reset Image Attribute Instance operations Start Instances Run Instances Stop Instances Reboot Instances Terminate Instances Describe Instances Describe Instance Attributes Modify Instance Attribute Reset Instance Attribute Key-pair operations Create Key Pair Describe Key Pairs Delete Key Pair Monitoring operations Monitor Instances Unmonitor Instances Security Group operations Create Security Group Authorize Security Group Ingress Describe Security Groups Revoke Security Group Ingress Delete Security Group create-security-group authorize-security-group-ingress describe-security-groups revoke-security-group-ingress delete-security-group monitor-instances unmonitor-instances create-key-pair describe-key-pairs delete-key-pair start-instances run-instances stop-instance reboot-instances terminate-instances describe-instances describe-instance-attribute modify-instance-attribute reset-instance-attribute create-image describe-images register-image deregister-image describe-image-attribute modify-image-attribute reset-image-attribute Operation name
48
Utility operations Get Console Output Windows operations Get Password Data Describe Bundle Tasks Cancel Bundle Tasks Bundle Instance Regions and Availability Zones operations Describe Regions Describe Availability Zones Elastic Block Store (EBS) operations Create Volume Describe Volumes Delete Volume Attach Volume Detach Volume Create Snapshot Describe Snapshots Delete Snapshot Describe Snapshot Attribute Modify Snapshot Attribute Reset Snapshot Attribute Elastic IP Address operations Allocate Address Associate Address Disassociate Address Describe Addresses Release Address allocate-address associate-address disassociate-address describe-addresses release-address create-volume describe-volumes delete-volume attach-volume detach-volume create-snapshot describe-snapshots delete-snapshot describe-snapshot-attribute modify-snapshot-attribute reset-snapshot-attribute describe-regions describe-availability-zones get-password-data describe-bundle-tasks cancel-bundle-task bundle-instance get-console-output
Adapter_Actions directory for the BMC Atrium Orchestrator Application Adapter for Amazon EC2
The Adapter_Actions directory contains all the functional processes that are available in the v1.0 directory, with simplified input values.
49
The common inputs for these processes are adapter name, wsdl-location, and endpoint-address. The functional processes in the Adapter_Actions directory internally invoke the relevant constructor processes in the Utilities directory.
Actor adapter requests and responses for the BMC Atrium Orchestrator Application Adapter for Amazon EC2
This section describes the adapter requests and responses for the Amazon EC2 actor adapter.
Amazon EC2 actor adapter

The adapter requests for the actor adapter uses a set of elements to execute a Web service call on Amazon EC2. The set of values used to make a Web service call is referred to as an operation. You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity.
Supported categories of operations
The actor adapter can perform the following categories of operations: Amazon Machine Image operations Instance operations Key pair operations Monitoring operations Security Group operations Utility operations Windows operations Regions and Availability Zones operations Elastic Block Store (EBS) operations Elastic IP Address operations The actor adapter supports the following operations: Adapter operations Type Amazon Machine Image operation Amazon Machine Image operation Amazon Machine Image operation Amazon Machine Image operation Amazon Machine Image operation Amazon Machine Image operations Process name Create Image Describe Images Register Image Description Creates an Amazon Machine Image (AMI) that uses an Amazon EBS root device from a running or stopped instance Retrieves information about Amazon resources Registers an AMI with Amazon EC2
Deregister Image Deregisters a specified AMI Describe Image Attribute Modify Image Attribute Returns information about an attribute of an AMI Modifies an attribute of an AMI
50
Amazon Machine Image operation Instance operation Instance operation Instance operation Instance operation Instance operation Instance operation Instance operation Instance operation Instance operation Key pair operation Key pair operation Key pair operation Security Group operation Security Group operation Security Group operation Security Group operation Security Group operation Monitoring operation Monitoring operation Utility operation Windows operation
Reset Image Attribute Start Instances Run Instances Stop Instances
Resets an attribute of an AMI to its default value Starts an instance with a Amazon Elastic Block Storage (EBS) volume as its root device Launches a specified number of AMI instances for which you have the required permissions Stops an instance with a Amazon Elastic Block Storage (EBS) volume as its root device
Reboot Instances Reboots the specified instances Terminate Instances Describe Instances Shuts down the specified instances Retrieves information about the instances that you own
Describe Returns attribute information for a specified instance Instance Attribute Modify Instance Attribute Reset Instance Attribute Create Key Pair Describe Key Pairs Delete Key Pair Create Security Group Authorize Security Group Ingress Describe Security Groups Revoke Security Group Ingress Delete Security Group Monitor Instances Unmonitor Instances Get Console Output Get Password Data Modifies an attribute for a specified instance Resets an instance attribute instance to the default value Creates a 2048-bit RSA key pair with the specified name Retrieves information about the key pairs that are available for your use Deletes a key pair, by removing the specified public key from Amazon EC2 Creates a new security group in Amazon EC2 Enables you to add permissions for a security group in Amazon EC2 Retrieves information about the security groups that you own Enables you to revoke permissions from the specified security group Enables you to delete a security group that you own Enables monitoring for a running instance Disables monitoring for a running instance Retrieves console output for the specified instance Retrieves the administrator password for instances running on Microsoft Windows
51
Windows operation Windows operation Windows operation Regions and Availability Zones operation Regions and Availability Zones operation Elastic Block Store (EBS) operation EBS operation EBS operation EBS operation EBS operation EBS operation EBS operation EBS operation EBS operation
Describe Bundle Tasks Cancel Bundle Tasks Bundle Instance Describe Regions
Describes the current bundling tasks Cancels a bundling operation Bundles a Windows instance Describes the Regions that are currently available to the account
Describe Displays the availability zones that are currently available to the Availability Zones account and their states Create Volume Describe Volumes Delete Volume Attach Volume Detach Volume Create Snapshot Describe Snapshots Delete Snapshot Describe Snapshot Attribute Modify Snapshot Attribute Reset Snapshot Attribute Allocate Address Associate Address Disassociate Address Describe Addresses Release Address Creates a new Amazon EBS volume to which any Amazon EC2 instance can attach within the same Availability Zone Describes the specified Amazon EBS volumes that you own Deletes an Amazon EBS volume that you own Attaches an Amazon EBS volume to a running instance and exposes the instance as the specified device Detaches an Amazon EBS volume from an instance Creates a snapshot of an Amazon EBS volume and stores it in Amazon S3 Returns information about Amazon EBS snapshots available to the user Deletes a snapshot of an Amazon EBS volume that you own Returns information about an attribute of a snapshot
EBS operation EBS operation Elastic IP Address operation Elastic IP Address operation Elastic IP Address operation Elastic IP Address operation Elastic IP Address operation
Adds or removes permission settings for the specified snapshot Resets permission settings for the specified snapshot Acquires an elastic IP address for use with your account Associates an elastic IP address with an instance Disassociates a specified elastic IP address from an instance to which it is assigned Lists elastic IP addresses assigned to your account or provides information about a specific address Releases an elastic IP address associated with your account
Adapter requests and responses for Security Group operations
52
This section illustrates the adapter requests and responses for Security Group operations.
Request and response for Revoke Security Group Ingress operation

The Revoke Security Group Ingress operation enables you to revoke permissions from the specified security group. While revoking permissions, you must use the same values specified for granting the permissions. The permissions for a security group are specified by: IP protocolTCP, UDP, or ICMP Source of the requestIP range or an Amazon EC2 user-group pair Source and destination port ranges for TCP and UDP Codes and types for ICMP The following figure shows the sample <items> XML element for the Revoke Security Group Ingress operation. Sample <items> XML element for the Revoke Security Group Ingress operation
<items> <item> <parameters> <user-id></user-id> <group-name></group-name> <ip-permissions>  <item> <ip-protocol></ip-protocol> <from-port></from-port> <to-port></to-port> <groups>  <item> <user-id></user-id> <group-name></group-name> </item> </groups> <ip-ranges>  <item> <cidr-ip></cidr-ip> </item> </ip-ranges> </item> </ip-permissions> </parameters> </item> </items>
The following table shows the adapter request elements for the Revoke Security Group Ingress operation. Adapter request elements for the Revoke Security Group Ingress operation Element Definition Required
53
<wsdl-location>
Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2
Conditional: Required if not specified in the request Examples: If specified in the http://ec2.amazonaws.com/doc/2009-11-30/ configuration and request, the value in the request http://ec2.amazonaws.com/doc/2011-02-28/ overrides the value in the configuration Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions Default value: US East region: http://us-east-1.ec2.amazonaws.com/ No
<endpoint-address>
<signature-properties> Specifies the mode for signing the adapter request Conditional; required if not specified in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data> <operation-name> <user-id> <group-name> Contains the name of the operation: revoke-security-group-ingress Specifies the Access Key ID for the Amazon web services Specifies the name of the security group to modify The security group name must be valid and must belong to your Amazon EC2 account. <ip-permissions> Specifies the set of permissions for the security group The <ip-permissions> element has the following child elements: <ip-protocol> <from-port> <to-port> <groups> <ip-ranges> <user-id> Specifies the protocol to be used to revoke permissions from the specified security group Valid values: tcp, udp, icmp Yes Yes No Yes
<ip-protocol>
Yes
54
<from-port>
Specifies the start of the port range for the TCP and UDP protocols, or an ICMP type number A value of -1 indicates a wild card (any ICMP code). Specifies the end of the port range for the TCP and UDP protocols, or an ICMP type number A value of -1 indicates a wild card (any ICMP code).
Yes
<to-port>
Yes
<groups>
Specifies the list of security group and user-id Yes pairs This element can not be used to specify a CIDR IP address. Specifies the list of CIDR IP ranges Yes
<ip-ranges>
The following figure shows a sample adapter request for the Revoke Security Group Ingress operation. Sample adapter request for the Revoke Security Group Ingress operation
55
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/ </wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>revoke-security-group-ingress</operation-name> <parameters> <user-id>AKIAJC5TEHAOKCDCZQ</user-id> <group-name>test1</group-name> <ip-permissions> <item> <ip-protocol>tcp</ip-protocol> <from-port>80</from-port> <to-port>80</to-port> <groups> <item> <user-id>122872856587</user-id> <group-name>sec1</group-name> </item> </groups> <ip-ranges/> </item> <item> <ip-protocol>tcp</ip-protocol> <from-port>10</from-port> <to-port>100</to-port> <ip-ranges> <item> <cidr-ip>205.192.0.0/16</cidr-ip> </item> <item> <cidr-ip>205.10.10.0/8</cidr-ip> </item> </ip-ranges> </item> </ip-permissions> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Revoke Security Group Ingress operation. Sample adapter response for the Revoke Security Group Ingress operation
56
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <RevokeSecurityGroupIngressResponse> <requestId>9f5082d8-a54c-4ca3-833d-e19e5b6e4eae</requestId> <return>true</return> </RevokeSecurityGroupIngressResponse> </amazon-ec2-response>
Request and response for Delete Security Group operation

The Delete Security Group operation enables you to delete a security group that you own. The following figure shows a sample <items> XML element for the Delete Security Group operation. Sample <items> XML element for the Delete Security Group operation
<items> <item> <parameters> <group-name></group-name> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Delete Security Group operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions Default value: US East region: http://us-east-1.ec2.amazonaws.com/
57
<signature-properties> Specifies the mode for signing the adapter request Conditional: Required if not specified in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data>
<operation-name> <group-name>
Contains the name of the operation: delete-security-group Specifies the name of the security group that you want to delete
Yes Yes
The following figure shows the sample adapter request for the Delete Security Group operation. Sample adapter request for the Delete Security Group operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>delete-security-group</operation-name> <parameters> <group-name>TestAPISecurityGroup</group-name> </parameters> </amazon-ec2-request>
The following figure shows the sample adapter response for the Delete Security Group operation. Sample adapter response for the Delete Security Group operation
58
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DeleteSecurityGroupResponse> <requestId>f208af00-b50b-4c8f-ace7-c4d09c8299c8</requestId> <return>true</return> </DeleteSecurityGroupResponse> </amazon-ec2-response>
Request and response for Authorize Security Group Ingress operation

The Authorize Security Group Ingress operation enables you to add permissions for a security group in Amazon EC2. The following figure shows the sample <items> XML element for the Authorize Security Group Ingress operation. Sample <items> XML element for the Authorize Security Group Ingress operation
<items> <item> <parameters> <user-id></user-id> <group-name></group-name> <ip-permissions>  <item> <ip-protocol></ip-protocol> <from-port></from-port> <to-port></to-port> <groups>  <item> <user-id></user-id> <group-name></group-name> </item> </groups> <ip-ranges>  <item> <cidr-ip></cidr-ip> </item> </ip-ranges> </item> </ip-permissions> </parameters> </item> </items>
The following table shows the adapter request elements for the Authorize Security Group Ingress operation.
59
Adapter request elements for the Authorize Security Group Ingress operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <user-id> <group-name>
Contains the name of the operation: authorize-security-group-ingress Specifies the Access Key ID for the Amazon web services Specifies the name of the security group to modify The security group name must be valid and must belong to your Amazon EC2 account.
Yes No Yes
60
<ip-permissions>
Specifies the set of permissions for the security group The <ip-permissions> element has the following child elements: <ip-protocol> <from-port> <to-port> <groups> <ip-ranges> <user-id>
Yes
<ip-protocol>
Specifies the protocol to be used to revoke permissions from the specified security group Valid values: tcp, udp, icmp Specifies the start of the port range for the TCP and UDP protocols, or an ICMP type number A value of -1 indicates a wild card (any ICMP code). Specifies the end of the port range for the TCP and UDP protocols, or an ICMP type number A value of -1 indicates a wild card (any ICMP code). Specifies the list of security group and user-id pairs This element cannot be used to specify a CIDR IP address. Specifies the list of CIDR IP ranges
Yes
<from-port>
Yes
<to-port>
Yes
<groups>
Yes
<ip-ranges>
Yes
The following figure shows a sample adapter request for the Authorize Security Group Ingress operation. Sample adapter request for the Authorize Security Group Ingress operation
61
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>authorize-security-group-ingress</operation-name> <parameters> <user-id>AKIAJC5TEHAOKCDCZQ</user-id> <group-name>test1</group-name> <ip-permissions> <item> <ip-protocol>tcp</ip-protocol> <from-port>80</from-port> <to-port>80</to-port> <groups> <item> <user-id>122872856587</user-id> <group-name>sec1</group-name> </item> </groups> <ip-ranges/> </item> <item> <ip-protocol>tcp</ip-protocol> <from-port>10</from-port> <to-port>100</to-port> <ip-ranges> <item> <cidr-ip>205.192.0.0/16</cidr-ip> </item> <item> <cidr-ip>205.10.10.0/8</cidr-ip> </item> </ip-ranges> </item> </ip-permissions> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Authorize Security Group Ingress operation. Sample adapter response for the Authorize Security Group Ingress operation
62
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <AuthorizeSecurityGroupIngressResponse> <requestId>9f5082d8-a54c-4ca3-833d-e19e5b6e4eae</requestId> <return>true</return> </AuthorizeSecurityGroupIngressResponse> </amazon-ec2-response>
Request and response for Create Security Group operation

The Create Security Group operation enables you to create a new security group. The security group name must be unique for each Amazon EC2 account. The following figure shows the sample <items> XML element for the Create Security Group operation. Sample <items> XML element for the Create Security Group operation
<items> <item> <parameters> <group-name></group-name> <group-description></group-description> </parameters> </item> </items>
The following table shows the adapter request elements for this request. Adapter request elements for the Create Security Group operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
63
<operation-name> <group-name>
Contains the name of the operation: create-security-group Specifies the name of the security group Valid values: alphanumeric characters, spaces, dashes, underscores Specifies the description for the security group Valid values: alphanumeric characters, spaces, dashes, underscores
Yes Yes
<group-description>
Yes
The following figure shows a sample adapter request for the Create Security Group operation. Sample adapter request for the Create Security Group operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>create-security-group</operation-name> <parameters> <group-name>TestAPISecurityGroup</group-name> <group-description>Test API SecurityGroup</group-description> </parameters> </amazon-ec2-request>
The following figure shows the sample adapter response for the Create Security Group operation. Sample adapter response for the Create Security Group operation
64
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CreateSecurityGroupResponse> <requestId>dedeb30e-93f0-4ad6-9071-1a92b07c06bc</requestId> <return>true</return> </CreateSecurityGroupResponse> </amazon-ec2-response>
Request and response for Describe Security Groups operation

The Describe Security Groups operations retrieves information about the security groups that you own. The following figure shows the sample <items> XML element for the Describe Security Groups operation. Sample <items> XML element for the Describe Security Groups operation
<items> <item> <parameters> <security-group-set>  <item> <group-name></group-name> </item> </security-group-set> </parameters> </item> </items>
The following table shows the adapter request elements for this request. Adapter request elements for the Describe Security Groups operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration
65
<endpoint-address>
No
<operation-name> <security-group-set>
Contains the name of the operation: describe-security-group Specifies the set of security groups containing the name of the security groups to be described
Yes Yes
The following figure shows a sample adapter request for the Describe Security Groups operation. Sample adapter request for the Describe Security Groups operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-security-groups</operation-name> <parameters> <security-group-set> <item> <group-name>test1</group-name> </item> </security-group-set> </parameters> </amazon-ec2-request>
66
The following figure shows the response for the sample adapter response for the Describe Security Groups operation. Sample adapter response for the Describe Security Groups operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeSecurityGroupsResponse> <requestId>3d33464d-1baa-4a7d-b9b2-7179c31945ae</requestId> <securityGroupInfo> <item> <ownerId>622872851117</ownerId> <groupName>test1</groupName> <groupDescription>testdescription</groupDescription> <ipPermissions> <item> <ipProtocol>tcp</ipProtocol> <fromPort>80</fromPort> <toPort>80</toPort> <groups> <item> <userId>622872851117</userId> <groupName>sec1</groupName> </item> </groups> <ipRanges/> </item> <item> <ipProtocol>tcp</ipProtocol> <fromPort>10</fromPort> <toPort>100</toPort> <groups/> <ipRanges> <item> <cidrIp>205.10.10.0/8</cidrIp> </item> <item> <cidrIp>205.192.0.0/16</cidrIp> </item> </ipRanges> </item> </ipPermissions> </item> </securityGroupInfo> </DescribeSecurityGroupsResponse> </amazon-ec2-response>
Adapter requests and responses for Elastic IP Address operations

This section illustrates the adapter requests and responses for the Elastic IP Address operations.
67
Request and response for the Allocate Address operation

The Allocate Address operation acquires an elastic IP address for use with your account. The following figure shows a sample <items> XML element for the Allocate Address operation. Sample <items> XML element for the Allocate Address operation
<items> <item> <parameters/> </item> </items>
Note This operation does not have any inputs; therefore, you must provide the above sample input with empty parameters.
The following table describes the adapter request elements for this request. Adapter request elements for the Allocate Address operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
68
<operation-name>
Contains the name of the operation: allocate-address
Yes
The following figure shows a sample adapter request for the Allocate Address operation. Sample adapter request for the Allocate Address operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>allocate-address</operation-name> <parameters/> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Allocate Address operation. Sample adapter response for the Allocate Address operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <AllocateAddressResponse> <requestId>ae745827-abe0-41dc-b1d7-89110939001f</requestId> <publicIp>184.73.215.42</publicIp> </AllocateAddressResponse> </amazon-ec2-response>
69
Request and response for the Associate Address operation

The Associate Address operation associates an elastic IP address with an instance. If the IP address is currently assigned to another instance, the IP address is assigned to a new instance. This is an idempotent operation (produces the same results no matter how many times it is performed). If you perform the operation more than once, Amazon EC2 does not return an error. The following figure shows a sample <items> XML element for the Associate Address operation. Sample <items> XML element for the Associate Address operation
<items> <item> <parameters> <public-ip></public-ip> <instance-id></instance-id> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Associate Address operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
70
<operation-name> <public-ip> <instance-id>
Contains the name of the operation: associate-address Specifies the IP address that you assign to the instance Specifies the instance to associate with the IP address
Yes Yes Yes
The following figure shows a sample adapter request for the Associate Address operation. Sample adapter request for the Associate Address operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>associate-address</operation-name> <parameters> <public-ip>184.73.215.42</public-ip> <instance-id>i-edd49186</instance-id> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Associate Address operation. Sample adapter response for the Associate Address operation
71
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <AssociateAddressResponse> <requestId>d417e51b-80a7-49eb-8fdc-45b6fbd89189</requestId> <return>true</return> </AssociateAddressResponse> </amazon-ec2-response>
Request and response for the Disassociate Address operation

The Disassociate Address operation disassociates a specified elastic IP address from an instance to which it is assigned. This is an idempotent operation. If you perform the operation more than once, Amazon EC2 does not return an error. The following figure shows a sample <items> XML element for the Disassociate Address operation. Sample <items> XML element for the Disassociate Address operation
<items> <item> <parameters> <public-ip></public-ip> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Disassociate Address operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
72
<operation-name> <public-ip>
Contains the name of the operation: disassociate-address Specifies the IP address that you are disassociating from an instance
Yes Yes
The following figure shows a sample adapter request for the Disassociate Address operation. Sample adapter request for the Disassociate Address operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>disassociate-address</operation-name> <parameters> <public-ip>184.73.215.42</public-ip> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Disassociate Address operation. Sample adapter response for the Disassociate Address operation
73
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DisassociateAddressResponse> <requestId>ab806552-8ec9-42bb-a891-38b774dd3b35</requestId> <return>true</return> </DisassociateAddressResponse> </amazon-ec2-response>
Request and response for Describe Addresses operation

The Describe Addresses operation lists the elastic IP addresses assigned to your account or provides information about a specific address. The following figure shows a sample <items> XML element for the Describe Addresses operation. Sample <items> XML element for the Describe Addresses operation
<items> <item> <parameters> <public-ips-set>  <item> <public-ip></public-ip> </item> </public-ips-set> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Describe Addresses operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration
74
<endpoint-address>
No
<operation-name> <public-ips-set>
Contains the name of the operation: describe-addresses Specifies the set of elastic IP addresses that you want to list
Yes Yes
The following figure shows a sample adapter request for the Describe Addresses operation. Sample adapter request for the Describe Addresses operation
75
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-addresses</operation-name> <parameters> <public-ips-set>  <item> <public-ip>184.73.215.42</public-ip> </item> </public-ips-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Describe Addresses operation. Sample adapter response for the Describe Addresses operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeAddressesResponse> <requestId>db831390-a155-45f5-bb8d-bec701c8874a</requestId> <addressesSet> <item> <publicIp>184.73.215.42</publicIp> <instanceId/> </item> </addressesSet> </DescribeAddressesResponse> </amazon-ec2-response>
Request and response for the Release Address operation

The Release Address operation releases an elastic IP address associated with your account. Releasing an IP address automatically disassociates it from any instance with which it is associated. If you run this operation on an elastic IP address that is already released, the address might get assigned to another account causing Amazon EC2 to return an error. The following figure shows a sample <items> XML element for the Release Address operation. Sample <items> XML element for the Release Address operation
76
<items> <item> <parameters> <public-ip></public-ip> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Release Address operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <public-ip>
Contains the name of the operation: release-address Specifies the IP address that you want to release
Yes Yes
77
The following figure shows a sample adapter request for the Release Address operation. Sample adapter request for the Release Address operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>release-address</operation-name> <parameters> <public-ip>184.73.215.42</public-ip> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Release Address operation. Sample adapter response for the Release Address operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ReleaseAddressResponse> <requestId>cd310e67-56b5-40d3-ad49-6d205d295ff3</requestId> <return>true</return> </ReleaseAddressResponse> </amazon-ec2-response>
Adapter requests and responses for Instance operations

This section illustrates the adapter requests and responses for the Instance operations.
Request and response for Describe Instances operation

The Describe Instances operation enables you to retrieve information about instances that you own. If you specify one or more instance IDs, the Describe Instances operation returns information for the specified instances. If you do not specify any instance IDs, the operation returns information for all relevant instances. If you specify an invalid instance ID, the operation returns a fault. If you specify an instance that you do not own, it will not be included in the results retrieved from Amazon EC2. The following figure shows a sample <items> XML element for the Describe Instances operation. Sample <items> XML element for the Describe Instances operation
78
<items> <item> <parameters> <instances-set>  <item> <instance-id></instance-id> </item> </instances-set> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
79
<operation-name> <instance-set>
Contains the name of the operation: describe-instances contains one or more instance IDs corresponding to the instances that you want to query for description
Yes Yes
The following figure shows a sample adapter request for the Describe Instances operation. Sample adapter request for the Describe Instances operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bd90bfd5</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Describe Instances operation. Sample adapter response for the Describe Instances operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeInstancesResponse> <requestId>b17d2e68-fbd2-484b-92c0-7ff7e7f3dbc6</requestId> <reservationSet> <item> <reservationId>r-094ccf61</reservationId> <ownerId>622872856407</ownerId> <groupSet> <item> <groupId>testlsec</groupId> </item> </groupSet> <instancesSet> <item> <instanceId>i-bd90bfd5</instanceId>
80
<imageId>ami-b232d0db</imageId> <instanceState> <code>16</code> <name>running</name> </instanceState> <privateDnsName>domU-12-31-38-00-29-A2.compute-1.internal </privateDnsName> <dnsName>ec2-174-129-149-12.compute-1.amazonaws.com </dnsName> <reason/> <keyName>testkeys</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes/> <instanceType>m1.small</instanceType> <launchTime>2010-01-06T10:36:45.000Z</launchTime> <placement> <availabilityZone>us-east-1a</availabilityZone> </placement> <kernelId>aki-94c527fd</kernelId> <ramdiskId>ari-96c527ff</ramdiskId> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress>10.252.46.80</privateIpAddress> <ipAddress>174.129.149.12</ipAddress> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda1</deviceName> <ebs> <volumeId>vol-0767a06e</volumeId> <status>attached</status> <attachTime>2010-01-06T10:36:50.000Z </attachTime> <deleteOnTermination>true </deleteOnTermination> </ebs> </item> </blockDeviceMapping> </item> </instancesSet> </item>
81
</reservationSet> </DescribeInstancesResponse> </amazon-ec2-response>
Request and response for the Stop Instances operation

The Stop Instances operation enables you to stop an instance that uses an Amazon EBS volume as the root device.
Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When an instance is stopped, the compute resources associated with the instance are released and you are not billed for hourly instance usage. However, your root partition Amazon EBS volume still retains your data, and you are charged for Amazon EBS volume usage. You can restart your instance at any time. The following figure shows a sample <items> XML element for the Stop Instances operation. Sample <items> XML element for the Stop Instances operations
The following table describes the elements for this adapter request. Adapter request elements for the Stop Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
82
<operation-name> <instances-set>
Contains the name of the operation: stop-instances Contains one or more instance IDs corresponding to the instances that you want to stop
Yes Yes
The following figure shows a sample adapter request for the Start Instances operation. Sample adapter request for the Stop Instances operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>stop-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bd90bfd5</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Stop Instances operation. Sample adapter response for the Stop Instances operation
83
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <StopInstancesResponse> <requestId>cab287ed-09f4-4abd-81b0-af332eca359e</requestId> <instancesSet> <item> <instanceId>i-bd90bfd5</instanceId> <currentState> <code>64</code> <name>stopping</name> </currentState> <previousState> <code>16</code> <name>running</name> </previousState> </item> </instancesSet> </StopInstancesResponse> </amazon-ec2-response>
Request and response for the Describe Instance Attribute operation

The Describe Instance Attribute operation enables you to retrieve information about an attribute of an instance. You can obtain information about only one attribute for each call. The following figure shows a sample <items> XML element for the Describe Instance Attribute operation. Sample <items> XML element for the Describe Instance Attribute operation
<items> <item> <parameters> <instance-id></instance-id>  <instance-type/> <kernel/> <ramdisk/> <user-data/> <instance-initiated-shutdown-behavior/> <root-device-name/> <block-device-mapping/> </parameters> </item> </items>
The following table shows the elements for this adapter request. Adapter request elements for the Describe Instance Attribute operation
84
Element <wsdl-location>
Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/
Required Conditional:
Required if no If specified in value in the re configuration
<endpoint-address>
No
<signature-properties>
Specifies the mode for signing the adapter request Conditional:
Required if no If <signatur "key-files" and <certif If <signatur "key-data"> and <certif
<operation-name> <instance-id> <instance-type>
Contains the name of the operation: describe-instance-attribute Specifies the instance ID for the instance whose attribute information is to be retrieved Specifies the type of the instance
Yes Yes
Conditional; required
<kernel> <ramdisk> <user-data> <instance-i <root-devic <block-devi
<kernel>
Specifies the kernel ID for the instance
<instance-t <ramdisk> <user-data> <instance-i <root-devic <block-devi
85
<ramdisk>
Specifies the RAM disk ID for the instance
<instance-t <kernel> <user-data> <instance-i <root-devic <block-devi
<user-data>
Specifies the user data for the instance
<instance-t <kernel> <ramdisk> <instance-i <root-devic <block-devi
<instance-initiated-shutdown-behavior> Specifies whether the Amazon EBS volumes for the instances are stopped or terminated when the instance is shut down
<instance-t <kernel> <ramdisk> <user-data> <root-devic <block-devi
<root-device-name>
Specifies the root device name of the instance For example, /dev/sda1
<instance-t <kernel> <ramdisk> <user-data> <instance-i <block-devi
86
<block-device-mapping>
Specifies the block device mapping set
<instance-t <kernel> <ramdisk> <user-data> <instance-i <root-devic
The following figure shows a sample adapter request for the Describe Instance Attribute operation. Sample adapter request for the Describe Instance Attribute operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-instance-attribute</operation-name> <parameters> <instance-id>i-bc6c52d4</instance-id> <user-data/> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Describe Instance Attribute operation. Sample adapter response for the Describe Instance Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeInstanceAttributeResponse> <requestId>44ba465a-165e-43cc-bcd3-70c8396fec6b</requestId> <instanceId>i-bc6c52d4</instanceId> <userData> <value><![CDATA[Test Data]]></value> </userData> </DescribeInstanceAttributeResponse> </amazon-ec2-response>
Request and response for the Terminate Instances operation
87
The Terminate Instances operation enables you to shut down one or more Amazon EC2 instances. If you invoke the Terminate Instances operation for an instance more than once, the operation still executes successfully. Note A terminated instance remains visible in Amazon EC2 for approximately one hour after termination.
The following figure shows a sample <items> XML element for the Terminate Instances operation. Sample <items> XML element for the Terminate Instances operation
The following table describes the elements for this adapter request. Adapter request elements for the Terminate Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
88
Specifies the name of the operation: terminate-instances Contains one or more instance IDs corresponding to the instances that you want to terminate
Yes Yes
The following figure shows a sample adapter request for the Terminate Instances operation. Sample adapter request for the Terminate Instances operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>terminate-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bd90bfd5</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Terminate Instances operation. Sample adapter response for the Terminate Instances operation
89
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <TerminateInstancesResponse> <requestId>8ed75e81-51bb-4dd3-9893-6e95411c8a23</requestId> <instancesSet> <item> <instanceId>i-bd90bfd5</instanceId> <currentState> <code>32</code> <name>shutting-down</name> </currentState> <previousState> <code>16</code> <name>running</name> </previousState> </item> </instancesSet> </TerminateInstancesResponse> </amazon-ec2-response>
Request and response for the Reset Instance Attribute operation

The Reset Instance Attribute operations resets the specified attribute of an instance to its default value. The following figure shows a sample <items> XML element for the Reset Instance Attribute operation. Sample <items> XML element for the Reset Instance Attribute operation
<items> <item> <parameters> <instance-id></instance-id>  <kernel/> <ramdisk/> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Reset Instance Attribute operation Element Definition Required
90
<wsdl-location>
<endpoint-address>
<operation-name> <instance-id> <kernel> <ramdisk>
Contains the name of the operation: reset-instance-attribute Specifies the instance ID for the instance whose attribute value is to be reset Specifies the kernel ID for the instance Specifies the RAM disk ID for the instance
Yes Yes No No
The following figure shows a sample adapter request for the Reset Instance Attribute operation. Sample adapter request for the Reset Instance Attribute operation
91
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>reset-instance-attribute</operation-name> <parameters> <instance-id>i-bc6c52d4</instance-id> <kernel/> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Reset Instance Attribute operation. Sample adapter response for the Reset Instance Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ResetInstanceAttributeResponse> <requestId>1e7b74a6-2327-4c22-92c1-f890a5def65c</requestId> <return>true</return> </ResetInstanceAttributeResponse> </amazon-ec2-response>
Request and response for the Run Instances operation

The Run Instances operation enables you to launch a specified number of instances of an AMI for which you have permissions. If Amazon EC2 cannot launch the specified minimum number of AMIs, no instances are launched. If there is insufficient capacity to launch the specified maximum number of AMIs, Amazon EC2 launches the minimum number of instances for each AMI and later allocates the remaining available instances. The following figure shows a sample <items> XML element for the Run Instances operation. Sample <items> XML element for the Run Instances operations
<items> <item> <parameters> <image-id></image-id> <min-count></min-count> <max-count></max-count>  <key-name></key-name>
92
<group-set>  <item> <group-id></group-id> </item> </group-set>  <additional-info></additional-info>  <user-data>  <data></data> </user-data>  <instance-type></instance-type>  <placement>  <availability-zone></availability-zone> </placement>  <kernel-id></kernel-id>  <ramdisk-id></ramdisk-id>  <block-device-mapping>  <item> <device-name></device-name> <virtual-name></virtual-name> <ebs>  <snapshot-id></snapshot-id>  <volume-size></volume-size>  <delete-on-termination></delete-on-termination> </ebs> <no-device/> </item> </block-device-mapping>  <monitoring>  <enabled></enabled> </monitoring>  <subnet-id></subnet-id>  <instance-initiated-shutdown-behavior> </instance-initiated-shutdown-behavior>
93
</parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Run Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional:
Required if no the request If specified in configuration a the value in th overrides the configuration No
<endpoint-address>
Required if no the configurat If <signaturemode = "key requires <private-ke and <certificat If <signaturemode = "key requires <private-ke and <certificat
<operation-name> <image-id>
Contains the name of the operation: run-instances Specifies the unique ID for the AMI
Yes Yes
94
<min-count>
Specifies the minimum number of instances to launch If Amazon EC2 cannot launch the value specified in the <min-count> element, no instances are launched. Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account Default value: 20
Yes
<max-count>
Specifies the maximum number of instances to Yes launch If Amazon EC2 cannot launch the value specified in the <max-count> element, the largest possible number greater than that specified in the <min-count> element is launched. Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account Default value: 20 Specifies the name of the key pair Specifies the security group or groups Specifies additional information for the instance or instances Contains the user data to be made available for the instance Specifies the type of the instance Valid values are: m1.small (default) m1.large m1.xlarge c1.medium c1.xlarge m2.2xlarge m2.4xlarge No No No No No
<key-name> <group-set> <additional-info> <user-data> <instance-type>
<availability-zone>
Specifies the placement constraints or availability zones for launching the required instances For example, us-east-1a is a sample value for the availability zone element. Specifies the Kernel ID with which to launch the instance
No
<kernel-id>
No
95
<block-device-mapping>
Specifies how the block devices are exposed to the instance Each mapping is comprised of a virtual-name and a device-name. The <block-device-mapping> element has the following child elements: <device-name> <virtual-name> <ebs> <snapshot-id> <volume-size> <delete-on-termination> <no-device>
No
<device-name> <virtual-name> <ebs>
Contains the device name (For example, /dev/sdh) No virtual-name: Contains the virtual device name Specifies the parameters used to automatically setup Amazon EBS volumes when the instance is launched Specifies the ID for the snapshot of the Amazon EBS volume Specifies the size of the Amazon EBS volume Specifies whether the Amazon EBS volume must be deleted when the instances is terminated Specifies whether the device name is suppressed while launching the instance Specifies whether to enable monitoring for the instance Valid values: true, false Specifies the subnet ID for the Amazon Virtual Private Cloud within which to launch the instance or instances No No
<snapshot-id> <volume-size> <delete-on-termination> <no-device> <monitoring>
No No No No No
<subnet-id>
No
<instance-initiated-shutdown-behavior> Specifies whether the Amazon EBS volumes used by the instance are terminated when the instance is shut down
No
The following figure shows a sample adapter request for the Run Instances operation. Sample adapter request for the Run Instances operation
96
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>run-instances</operation-name> <parameters> <image-id>ami-b232d0db</image-id> <min-count>1</min-count> <max-count>1</max-count>  <key-name>testkeys</key-name> <group-set>  <item> <group-id>testsec</group-id> </item> </group-set>  <additional-info>Test additional data</additional-info>  <user-data>  <data>Test Data</data> </user-data> <instance-type>m1.small</instance-type>  <placement>  <availability-zone>us-east-1a</availability-zone> </placement>  <monitoring>  <enabled>false</enabled> </monitoring> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Run Instances operation. Sample adapter response for the Run Instances operation
97
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <RunInstancesResponse> <requestId>2a6cc23d-d1ac-4dbf-bccc-9bf9d16be7e2</requestId> <reservationId>r-094ccf61</reservationId> <ownerId>622872856407</ownerId> <groupSet> <item> <groupId>testlsec</groupId> </item> </groupSet> <instancesSet> <item> <instanceId>i-bd90bfd5</instanceId> <imageId>ami-b232d0db</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName/> <dnsName/> <reason/> <keyName>testkeys</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes/> <instanceType>m1.small</instanceType> <launchTime>2010-01-06T10:36:45.000Z</launchTime> <placement> <availabilityZone>us-east-1a</availabilityZone> </placement> <kernelId>aki-94c527fd</kernelId> <ramdiskId>ari-96c527ff</ramdiskId> <monitoring> <state>disabled</state> </monitoring> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping/> </item> </instancesSet> </RunInstancesResponse> </amazon-ec2-response>
The following figure shows a sample adapter request for the Run Instances operation with the <block-device mapping> element. Sample adapter request for the Run Instances operation with the <block-device mapping> element
98
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>run-instances</operation-name> <parameters> <image-id>ami-26df324f</image-id> <min-count>1</min-count> <max-count>1</max-count> <key-name>ritukeys</key-name> <group-set> <item> <group-id>usersec</group-id> </item> </group-set> <additional-info>Test additional-info tag</additional-info> <user-data> <data>Test Runinstances</data> </user-data> <instance-type>m1.small</instance-type> <placement> <availability-zone>us-east-1b</availability-zone> </placement> <kernel-id>aki-94c527fd</kernel-id> <ramdisk-id>ari-96c527ff</ramdisk-id> <block-device-mapping> <item> <device-name>/dev/sda1</device-name> <virtual-name>Test Volume</virtual-name> <ebs> <snapshot-id>snap-a8f58ac1</snapshot-id> <volume-size>15</volume-size> <delete-on-termination>true</delete-on-termination> </ebs> </item> </block-device-mapping> <monitoring> <enabled>false</enabled> </monitoring> <instance-initiated-shutdown-behavior>stop </instance-initiated-shutdown-behavior> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Run Instances operation with the <block-device mapping> element. Sample adapter response for the Run Instances operation with the <block-device mapping> element
99
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <RunInstancesResponse> <requestId>45771dc7-2bc5-4ff9-b2cd-4b8c26c33ca1</requestId> <reservationId>r-e868e280</reservationId> <ownerId>622872856407</ownerId> <groupSet> <item> <groupId>usersec</groupId> </item> </groupSet> <instancesSet> <item> <instanceId>i-e84c7f80</instanceId> <imageId>ami-26df344f</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName /> <dnsName /> <reason /> <keyName>ritukeys</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes /> <instanceType>m1.small</instanceType> <launchTime>2010-01-15T09:30:54.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> </placement> <kernelId>aki-94c528fd</kernelId> <ramdiskId>ari-96c528ff</ramdiskId> <monitoring> <state>disabled</state> </monitoring> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping /> </item> </instancesSet> </RunInstancesResponse> <amazon-ec2-response>
Request and response for the Start Instances operation

The Start Instances operation enables you to start an instance that uses an Amazon EBS volume as the root device.
100
You can quickly start and stop instances using Amazon EBS volumes as root devices. When an instance is stopped, the resources used by the instance are released and you are not billed for hourly instance usage. Amazon EC2 also allows you to restart a stopped instance. The following figure shows a sample <items> XML element for the Start Instances operation. Sample <items> XML element for the Start Instances operations
The following table describes the elements for this adapter request. Adapter request elements for the Start Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
101
Contains the name of the operation: start-instances Contains one or more instance IDs corresponding to the instances that you want to start
Yes Yes
The following figure shows a sample adapter request for the Start Instances operation. Sample adapter request for the Start Instances operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>start-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bd90bfd5</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Start Instances operation. Sample adapter response for the Start Instances operation
102
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <StartInstancesResponse> <requestId>c0368c77-e7f5-43d2-8d4f-c3122fd19788</requestId> <instancesSet> <item> <instanceId>i-bd90bfd5</instanceId> <currentState> <code>0</code> <name>pending</name> </currentState> <previousState> <code>80</code> <name>stopped</name> </previousState> </item> </instancesSet> </StartInstancesResponse> </amazon-ec2-response>
Request and response for the Reboot Instances operation

The Reboot Instances operation enables you to request a reboot of one or more instances. The Reboot Instances operation is asynchronous and this operation queues a request in Amazon EC2 to reboot the specified instance or instances. Note The Reboot Instances operation succeeds only if the instances are valid and if the instances belong to you. Amazon EC2 ignores requests to reboot terminated instances.
The following figure shows a sample <items> XML element for the Reboot Instances operation. Sample <items> XML element for the Reboot Instances operation
103
The following table describes the elements for the adapter request. Adapter request elements for the Reboot Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
Contains the name of the operation: reboot-instances Contains one or more instance IDs corresponding to the instances that you want to reboot
Yes Yes
The following figure shows a sample adapter request for the Reboot Instances operation. Sample adapter request for the Reboot Instances operation
104
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>reboot-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-f307589b</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Reboot Instances operation. Sample adapter response for the Reboot Instances operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <RebootInstancesResponse> <requestId>e0e0b0fb-b182-4fdb-b3a6-9a2752418fb2</requestId> <return>true</return> </RebootInstancesResponse> </amazon-ec2-response>
Request and response for the Modify Instance Attribute operation

The Modify Instance Attribute operation enables you to modify an attribute of an instance. You can modify only one attribute per call. The following figure shows a sample <items> XML element for the Modify Instance Attribute operation. Sample <items> XML element for the Modify Instance Attribute operation
105
<items> <item> <parameters> <instance-id></instance-id> <instance-type> <value></value> </instance-type> <kernel> <value></value> </kernel> <ramdisk> <value></value> </ramdisk> <user-data> <value></value> </user-data> <instance-initiated-shutdown-behavior> <value></value> </instance-initiated-shutdown-behavior> <block-device-mapping>  <item> <device-name></device-name>  <virtual-name></virtual-name> <ebs> <volume-id></volume-id>  <delete-on-termination></delete-on-termination> </ebs> <no-device/> </item> </block-device-mapping> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Modify Instance Attribute operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional:
Required if no the request If specified in configuration a the value in th overrides the configuration
106
<endpoint-address>
No
Required if no the configurat If <signaturemode = "key requires <private-ke and <certificat If <signaturemode = "key requires <private-ke and <certificat
<operation-name> <instance-id> <instance-type> <kernel> <ramdisk> <user-data>
Contains the name of the operation: modify-instance-attribute Specifies the instance ID for the instance whose attribute information is to be retrieved Specifies the type of the instance Specifies the kernel ID for the instance Specifies the RAM disk ID for the instance Specifies the user data for the instance
Yes Yes No No No No No
<instance-initiated-shutdown-behavior> Specifies whether the Amazon EBS volumes for the instances are stopped or terminated when the instance is shut down <block-device-mapping> Specifies the Block device mapping set
No
The following figure shows a sample adapter request for the Modify Instance Attribute operation. Sample adapter request for the Modify Instance Attribute operation
107
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>modify-instance-attribute</operation-name> <parameters> <instance-id>i-bc6c52d4</instance-id> <instance-type> <value>c1.medium</value> </instance-type> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Modify Instance Attribute operation. Sample adapter response for the Modify Instance Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ModifyInstanceAttributeResponse> <requestId>b2544b9e-65e1-4fd2-b5b4-0e47fbadf6d3</requestId> <return>true</return> </ModifyInstanceAttributeResponse> </amazon-ec2-response>
Adapter request and response for the Amazon Machine Image operations
This section illustrates the adapter request and response for the Amazon Machine Image operations.
Request and response for the Deregister Image operation

The Deregister Image operation enables you to deregister a specified AMI. After you deregister an AMI, you cannot use the AMI to launch new instances. The following figure shows a sample <items> XML element for the Deregister Image operation. Sample <items> XML element for the Deregister Image operation
108
<items> <item> <parameters> <image-id></image-id> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Deregister Image operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <image-id>
Contains the name of the operation: deregister-image Specifies the unique ID of the AMI assigned during registration
Yes Yes
109
The following figure shows a sample adapter request for the Deregister Image operation. Sample adapter request for the Deregister Image operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>deregister-image</operation-name> <parameters> <image-id>ami-8d618ee4</image-id> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Deregister Image operation. Sample adapter response for the Deregister Image operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DeregisterImageResponse> <requestId>40d855a5-6eab-4c91-bed1-13e5c1d16c15</requestId> <return>true</return> </DeregisterImageResponse> </amazon-ec2-response>
Request and response for the Describe Images operation

The Describe Images operation returns information about Amazon Machine Images (AMIs), Available Kernel Images (AKIs), and Amazon Ram Disk Images (ARIs). The retrieved information includes image type, product codes, architecture, kernel IDs, and RAM disk IDs. You can use the Describe Images operation only with images available to you. Images available to you, which include: Public images Private images that you own Private images owned by other users for which you have explicit launch permissions The following figure shows a sample <items> XML element for the Describe Images operation. Sample <items> XML element for the Describe Images operation
110
<items> <item> <parameters>  <executable-by-set>  <item> <user></user> </item> </executable-by-set> <images-set>  <item> <image-id></image-id> </item> </images-set>  <owners-set>  <item> <owner></owner> </item> </owners-set> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Images operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Required
Conditional: Required if not specified in the request Examples: If specified in the http://ec2.amazonaws.com/doc/2009-11-30/ configuration and request, the value in the request http://ec2.amazonaws.com/doc/2011-02-28/ overrides the value in the configuration Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions Default value: US East region: http://us-east-1.ec2.amazonaws.com/ No
<endpoint-address>
111
<signature-properties> Specifies the mode for signing the adapter request Conditional Required if not specified in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data> <operation-name> executable-by-set> Contains the name of the operation: describe-images Returns AMIs for which you have explicit launch permissions To include AMIs, you can use the following IDs: your Amazon account ID* self: AMIs for which you have explicit launch permissions all: AMIs with public launch permissions Specifies the name of the AMI provided during image creation Specifies the AMI IDs to describe Yes No
<name> <image-set> <owner-set>
Yes No
Contains information about an owner and returns No AMIs owned by the specified owner You can specify multiple owners. To include AMIs, you can use the following IDs: amazon: AMIs owned by Amazon self: AMIs owned by you
The following figure shows a sample adapter request for the Describe Images operation. Sample adapter request for the Describe Images operation
112
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-images</operation-name> <parameters> <executable-by-set/> <images-set/> <owners-set> <item> <owner>self</owner> </item> </owners-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Describe Images operation. Sample adapter response for the Describe Images operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeImagesResponse> <requestId>4c81c507-2644-42b0-8454-f2c6d34d7c13</requestId> <imagesSet> <item> <imageId>ami-82e301eb</imageId> <imageLocation>testk/kwinkeys.manifest.xml</imageLocation> <imageState>available</imageState> <imageOwnerId>622872856407</imageOwnerId> <isPublic>false</isPublic> <architecture>i386</architecture> <imageType>machine</imageType> <platform>windows</platform> <rootDeviceType>instance-store</rootDeviceType> <blockDeviceMapping/> </item> </imagesSet> </DescribeImagesResponse> </amazon-ec2-response>
Request and response for the Modify Image Attribute operation

The Modify Image Attribute operation enables you to modify an attribute of an AMI.
113
The following figure shows a sample <items> XML element for the Modify Image Attribute operation. Sample <items> XML element for the Modify Image Attribute operation
<items> <item> <parameters> <image-id></image-id>  <launch-permission>  <add>  <item> <user-id></user-id> </item> <item> <group></group> </item> </add> </launch-permission> <product-codes>  <item> <product-code></product-code> </item> </product-codes> <description> <value></value> </description> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Modify Image Attribute operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration
114
<endpoint-address>
No
<operation-name> <image-id> <description> <launch-permission>
Contains the name of the operation: modify-image-attribute
Yes
Specifies the ID of the AMI whose attribute is to be Yes modified Specifies the description of the AMI provided during image creation Specifies the launch permissions associated with the AMI add: Adds permission remove: Removes permission user-id: Specifies the Amazon Web Services (AWS) Access Key ID group: Specifies the name of the group. Currently, supports the all group. Note You can use either add or remove permission. Do not use both, add and remove permissions together. No No
<product-codes>
Specifies the product code associated with the AMI
No
The following figure shows a sample adapter request for the Modify Image Attribute operation.
115
Sample adapter request for the Modify Image Attribute operation

amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>modify-image-attribute</operation-name> <parameters> <image-id>ami-b9a648d0</image-id> <launch-permission> <add> <item> <group>all</group> </item> </add> </launch-permission> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Modify Image Attribute operation. Sample adapter response for the Modify Image Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ModifyImageAttributeResponse> <requestId>7d6b6de9-204c-4901-856e-f89b3460d114</requestId> <return>true</return> </ModifyImageAttributeResponse> </amazon-ec2-response>
Request and response for the Reset Image Attribute operation

The Reset Image Attribute operation resets an attribute of an AMI to its default value. The following figure shows a sample <items> XML element for the Reset Image Attribute operation. Sample <items> XML element for the Reset Image Attribute operation
116
<items> <item> <parameters> <image-id></image-id> <launch-permission/> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Reset Image Attribute operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name>
Contains the name of the operation: reset-image-attribute
Yes
117
<image-id> <launch-permission>
Specifies the ID of the AMI on which the attribute is to be reset Specifies the launch permissions set for the AMI This attribute is reset for the specified instance.
Yes No
The following figure shows a sample adapter request for the Reset Image Attribute operation. Sample adapter request for the Reset Image Attribute operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>reset-image-attribute</operation-name> <parameters> <image-id>ami-82e301eb</image-id> <launch-permission/> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Reset Image Attribute operation. Sample adapter response for the Reset Image Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ResetImageAttributeResponse> <requestId>7e05155d-a7f8-47d2-ac39-c0a17bb5e860</requestId> <return>true</return> </ResetImageAttributeResponse> </amazon-ec2-response>
Request and response for the Create Image operation

The Create Image operation creates an Amazon Machine Image (AMI) that uses an Amazon Elastic Block Store (EBS) root device from a running or stopped instance. The following figure shows a sample <items> XML element for the Create Image operation. Sample <items> XML element for the Create Image operation
118
<items> <item> <parameters> <instance-id></instance-id> <name></name>  <description></description>  <no-reboot></no-reboot> </parameters> </item> </items>
The following table shows the adapter request elements for the Create Image operation. Adapter request elements for the Create Image operation
Element <wsdl-location>>
Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/
Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
119
<operation-name> <instance-id> <name> <description> <no-reboot>
Contains the name of the operation: create-image Contains the ID of the instance Contains the name of the AMI Contains the description of the AMI Specifies whether Amazon EC2 attempts to cleanly shut down the instance before creating the image and reboots the instance later (when set to false) Valid values: true, false (default) When this element is set to true: Amazon EC2 does not shut down the instance before creating the image File system integrity on the created image is not guaranteed
Yes Yes Yes No No
The following figure shows a sample adapter request for the Create Image operation. Sample adapter request for the Create Image operation
120
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>create-image</operation-name> <parameters> <instance-id>i-5162d13a</instance-id> <name>Fedora Basic</name> <description>Image description</description> <no-reboot>false</no-reboot> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Create Image operation. Sample adapter response for the Create Image operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CreateImageResponse> <requestId>bb424c4c-7139-4a95-aa41-6cd8bbdd37d2</requestId> <imageId>ami-8d618ee4</imageId> </CreateImageResponse> </amazon-ec2-response>
Request and response for the Describe Image Attribute operation

The Describe Image Attribute operation returns information about an attribute of an Amazon Machine Image (AMI). You can specify only one attribute per call. The following figure shows a sample <items> XML element for the Describe Image Attribute operation. Sample <items> XML element for the Describe Image Attribute operation
121
<items> <item> <parameters> <image-id></image-id>  <description/> <launch-permission/> <product-codes/> <kernel/> <ramdisk/> <block-device-mapping/> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Image Attribute operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
122
<operation-name> <image-id> <description> <launch-permission> <product-codes> <kernel> <ramdisk>
Contains the name of the operation: describe-image-attribute
Yes
Specifies the ID of the AMI for which an attribute is Yes described Specifies the description of the AMI provided during image creation Specifies the launch permissions associated with the AMI Specifies the product code associated with the AMI Specifies the ID of the kernel associated with the AMI Specifies the ID of the RAM disk associated with the AMI No No No No No No
<block-device-mapping> Specifies the mapping that defines native device names that must be used when exposing virtual devices
The following figure shows a sample adapter request for the Describe Image Attribute operation. Sample adapter request for the Describe Image Attribute operation
123
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-image-attribute</operation-name> <parameters> <image-id>ami-8d618ee4</image-id> <description/> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Image Attribute operation. Sample adapter response for the Describe Image Attribute operation
amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeImageAttributeResponse> <requestId>3b6818a2-9615-46e8-b9e7-6e86b1c24515</requestId> <imageId>ami-8d618ee4</imageId> <description> <value>Image description</value> </description> </DescribeImageAttributeResponse> </amazon-ec2-response>
Request and response for the Register Image operation

The Register Image operation enables you to register a specified AMI with Amazon EC2. You should register images before launching them. Each AMI is associated with a unique ID. The Amazon EC2 service provides these unique IDs through this operation. If needed, you can deregister an AMI at any time. The following figure shows a sample <items> XML element for the Register Image operation. Sample <items> XML element for the Register Image operation
124
<items> <item> <parameters>  <image-location></image-location> <name></name>  <description></description>  <architecture></architecture>  <kernel-id></kernel-id>  <ramdisk-id></ramdisk-id>  <root-device-name></root-device-name>  <block-device-mapping>  <item> <device-name></device-name>  <virtual-name></virtual-name> <ebs>  <snapshot-id></snapshot-id>  <volume-size></volume-size>  <delete-on-termination></delete-on-termination> </ebs> <no-device/> </item> </block-device-mapping> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Register Image operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration
125
<endpoint-address>
No
<operation-name> <image-location>
Contains the name of the operation: register-image
Yes
Specifies the full path to the AMI manifest in Yes Amazon Simple Storage Service (S3) Amazon S3 is storage for the Internet. Amazon S3 provides a simple web services interface that you can use to store and retrieve any amount of data, at any time, from anywhere on the web. Specifies the name of the AMI provided during image creation Specifies the description of the AMI provided during image creation Specifies the architecture of the image Valid values: i386, x86_64 architecture Specifies the ID of the kernel to select Specifies the ID of the RAM disk to select Specifies the root device name (For example, /dev/sda1) Yes No No No No No
<name> <description> <architecture> <kernel-id> <ramdisk-id> <root-device-name>
126
<block-device-mapping> Specifies how block devices are exposed to the instance Each mapping is made up of a virtualName and a deviceName or device-name. device-name: Specifies the device name (For example, /dev/sdh) virtual-name: Specifies the virtual device name ebs: Specifies the parameters used to setup Amazon EBS volumes automatically when the instance is launched snapshot-id: Specifies the ID of the snapshot volume-size: Specifies the size of the volume delete-on-termination: Specifies whether the Amazon EBS volume is deleted when the instance is terminated no-device: Specifies the device name to suppress during instance launch
No
The following figure shows a sample adapter request for the Register Image operation. Sample adapter request for the Register Image operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>register-image</operation-name> <parameters> <image-location>/testuser/userwinkeys.manifest.xml</image-location> <name>TestImagenew</name> <description>Test Description new</description> <architecture>i386</architecture> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Register Image operation. Sample adapter response for the Register Image operation
127
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <RegisterImageResponse> <requestId>8139eeb6-e198-4b2f-a015-24b0f002f97d</requestId> <imageId>ami-5b9b7532</imageId> </RegisterImageResponse> </amazon-ec2-response>
Adapter requests and responses for Monitoring operations

This section illustrates the adapter requests and responses for the Monitoring operations.
Request and response for the Unmonitor Instances operation

The Unmonitor Instances operation enables you to disable monitoring for a running instance. The following figure shows a sample <items> XML element for the Unmonitor Instances operation. Sample <items> XML element for the Unmonitor Instances operation
The following table shows the adapter request elements for this request. Adapter request elements for the Unmonitor Instances operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration
128
<endpoint-address>
No
Contains the name of the operation: unmonitor-instances contains the set of instances for which monitoring is to be disabled
Yes Yes
The following figure shows a sample adapter request for the Unmonitor Instances operation. Sample adapter request for the Unmonitor Instances operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>unmonitor-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bc6c52d4</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
129
The following figure shows the response for the sample Unmonitor Instances operation. Sample adapter response for the Unmonitor Instance operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <UnmonitorInstancesResponse> <requestId>1793f584-d1ba-4cdc-9efe-0eceffb4bc8a</requestId> <instancesSet> <item> <instanceId>i-bc6c52d4</instanceId> <monitoring> <state>disabled</state> </monitoring> </item> </instancesSet> </UnmonitorInstancesResponse> </amazon-ec2-response>
Request and response for Monitor Instances operation

The Monitor Instances operation enables you to monitor a running instance. The following figure shows a sample <items> XML element for the Monitor Instances operation. Sample <items> XML element for the Monitor Instances operation
The following table shows the adapter request elements for this request. Adapter request elements for the Monitor Instances operation Element Definition Required
130
<wsdl-location>
<endpoint-address>
Contains the name of the operation: monitor-instances Contains the set of instance IDs for instances to be monitored
Yes Yes
The following figure shows a sample adapter request for the Monitor Instances operation. Sample adapter request for the Monitor Instances operation
131
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>monitor-instances</operation-name> <parameters> <instances-set> <item> <instance-id>i-bc6c52d4</instance-id> </item> </instances-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Monitor Instances operation. Sample adapter response for the Monitor Instances operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <MonitorInstancesResponse> <requestId>2244f4d0-e57d-45d1-a608-f041364e878d</requestId> <instancesSet> <item> <instanceId>i-bc6c52d4</instanceId> <monitoring> <state>enabled</state> </monitoring> </item> </instancesSet> </MonitorInstancesResponse> </amazon-ec2-response>
Adapter requests and responses for the Utility operation

This section illustrates the adapter request and response for the Utility operation.
Request and response for the Get Console Output operation

The Get Console Output operation retrieves console output for a specified instance. The console output for an instance is buffered and posted after an instance is booted, rebooted, or terminated. Amazon EC2 preserves the most recent 64 KB output, which is available for at least one hour after the latest post to the console output.
132
The following figure shows the sample <items> XML element for the Get Console Output operation. Sample <items> XML element for the Get Console Output operation
<items> <item> <parameters> <instance-id></instance-id> </parameters> </item> </items>
The following table describes the adapter request elements for the Get Console Output operation. Adapter request elements for the Get Console Output operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
133
<operation-name> <instance-id>
Contains the name of the operation: get-console-output
Yes
Specifies the ID of the instance for which you want Yes console output
The following figure shows a sample adapter request for the Get Console Output operation. Sample adapter request for the Get Console Output operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>get-console-output</operation-name> <parameters> <instance-id>i-6448440c</instance-id> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Get Console Output operation. Sample adapter response for the Get Console Output operation
134
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <GetConsoleOutputResponse> <requestId>30d8baba-9ea1-440a-b056-9dfda1561cd5</requestId> <instanceId>i-6448440c</instanceId> <timestamp>2010-01-27T08:17:15.000Z</timestamp> <output> <![CDATA[<Password> Vvyx7lZUUVsjNvmaShQ1cH6cwBZYjyq6JK1hZS8krWrwL j/HftPfDs/+bNW6VIvuFUg2o9KsctsKbe2ZymjSKuc6+AYAN2x2ZCtzAsz kwUz3Ppj23udoh5gwg7UtG34nbjRX0VUXJdj2OSnYg4q+pRH7SLH481n08 IU9ipad26yHTa8npaYv0PhheIEmqyHHTYoY7f91NcdM+EnerG+c8JnWVWiX yn98Xlvo4q8SNXRHbFsGevCHgtQHGNdy1TIZyhG7Qxgj7D6bqB89aX PuJFvqMswsrpb3mxJ1ESoN37YeJO8xGz6t4oVh8X2I7nG2uBFEDMOt 460sKUfm7YKgRA== </Password> <RDPCERTIFICATE> <DN>CN=I-6448440c, OU=EC2, O=Amazon.com </DN><THUMBPRINT>A5F95577C2B87DA858644773D3 43961349D3B18F</THUMBPRINT> </RDPCERTIFICATE> 7/2010 12:16:58 AM: Message: Ec2Config Service is rebooting the instance. Please be patient. ]]> </output> </GetConsoleOutputResponse> </amazon-ec2-response>
Adapter requests and responses for Elastic Block Store operations

This section illustrates the adapter requests and responses for the Elastic Block Store (EBS) operations.
Request and response for the Create Snapshot operation

The Create Snapshot operation enables you to create a snapshot of an Amazon EBS volume and store it in Amazon S3. You can use a snapshot for backup, to make identical copies of instance devices, and to save data before shutting down an instance. The following figure shows a sample <items> XML element for the Create Snapshot operation. Sample <items> XML element for the Create Snapshot operation
135
<items> <item> <parameters> <volume-id></volume-id>  <description></description> </parameters> </item> </items>
The following table shows adapter request elements for the Create Snapshot operation. Adapter request elements for the Create Snapshot operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name>
Contains the name of the operation: ceate-snapshot
Yes
136
<volume-id> <description>
Specifies the ID of the Amazon EBS volume of which you want to take a snapshot Describes the Amazon EBS snapshot
Yes No
The following figure shows a sample adapter request for the Create Snapshot operation. Sample adapter request for the Create Snapshot operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>create-snapshot</operation-name> <parameters> <volume-id>vol-679d280e</volume-id>  <description>Test Description</description> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Create Snapshot operation. Sample adapter response for the Create Snapshot operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CreateSnapshotResponse> <requestId>a83a15b3-ece7-4a17-9078-a178a4d40890</requestId> <snapshotId>snap-62a6700a</snapshotId> <volumeId>vol-679d280e</volumeId> <status>pending</status> <startTime>2010-04-20T08:06:25.000Z</startTime> <progress/> <ownerId>622872856407</ownerId> <volumeSize>1</volumeSize> <description>Test Description</description> </CreateSnapshotResponse> </amazon-ec2-response>
Request and response for the Create Volume operation

The Create Volume operation enables you to create a new Amazon EBS volume to which any Amazon EC2 instance can attach within the same Availability Zone.
137
The following figure shows a sample <items> XML element for the Create Volume operation. Sample <items> XML element for the Create Volume operation
<items> <item> <parameters>  <size></size>  <snapshot-id></snapshot-id> <availability-zone></availability-zone> </parameters> </item> </items>
The following table shows adapter request elements for the Create Volume operation. Adapter request elements for the Create Volume operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
138
<operation-name> <availability-zone> <size> <snapshot-id>
Contains the name of the operation: create-volume Specifies the Availability Zone in which to create the new volume Specifies the size of the volume, in GB Valid values: 1 to 1024 Specifies the snapshot from which to create the new volume
Yes Yes Conditional; required when not creating a volume from a snapshot No
The following figure shows a sample adapter request for the Create Volume operation. Sample adapter request for the Create Volume operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>create-volume</operation-name> <parameters>  <size>15</size>  <snapshot-id>snap-cfa2b8a6</snapshot-id> <availability-zone>us-east-1a</availability-zone> </parameters> </amazon-ec2-request>
139
The following figure shows a sample adapter response for the Create Volume operation. Sample adapter response for the Create Volume operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CreateVolumeResponse> <requestId>5cc661e1-af4d-4a23-88d2-ad02c95920a2</requestId> <volumeId>vol-e14fec88</volumeId> <size>15</size> <snapshotId>snap-cfa2b8a6</snapshotId> <availabilityZone>us-east-1a</availabilityZone> <status>creating</status> <createTime>2010-03-31T08:14:49.000Z</createTime> </CreateVolumeResponse> </amazon-ec2-response>
Request and response for the Describe Snapshots operation

The Describe Snapshots operation returns information about Amazon EBS snapshots available to the user. You can modify the list of snapshots returned by specifying snapshot IDs, snapshot owners, or users with create volume permissions. If no options are specified, Amazon EC2 returns all snapshots for which the user has create volume permissions. If you specify one or more snapshot IDs, only snapshots that have the specified IDs are returned. If you specify an invalid snapshot ID, an error is returned. If you specify a snapshot ID for which you do not have access, the snapshot will not be included in the returned results. If you specify one or more snapshot owners, only snapshots from the specified owners and for which you have access are returned. The results can include the Amazon Web Services (AWS) Account IDs of the specified owners, amazon for snapshots owned by Amazon, or self for snapshots that you own. If you specify a list of restorable users, only users that have create snapshot permissions for the snapshots are returned. You can specify AWS Account IDs (if you own the snapshot(s)), self for snapshots for which you own or have explicit permissions, or all for public snapshots.
The following figure shows a sample <items> XML element for the Describe Snapshots operation. Sample <items> XML element for the Describe Snapshots operation
140
<items> <item> <parameters> <snapshot-set>  <item> <snapshot-id></snapshot-id> </item> </snapshot-set>  <owners-set>  <item> <owner></owner> </item> </owners-set>  <restorable-by-set>  <item> <user></user> </item> </restorable-by-set> </parameters> </item> </items>
The following table shows adapter request elements for the Describe Snapshots operation. Adapter request elements for the Describe Snapshots operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
141
<operation-name> <snapshot-set> <owners-set>
Contains the name of the operation: describe-snapshots Specifies the set of Amazon EBS snapshots to be described Specifies the set of owners that can create volumes from the instance This element returns snapshots owned by the specified owner. Valid Values: self, amazon, AWS Account ID Specifies the set of users that can create volumes from the snapshot You must specify the Account ID of a user that can create volumes from the snapshot. Specifies the ID of the Amazon EBS snapshot to be described
Yes No No
<restorable-by-set>
No
<snapshot-id>
No
The following figure shows a sample adapter request for the Describe Snapshots operation. Sample adapter request for the Describe Snapshots operation
142
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-snapshots</operation-name> <parameters> <snapshot-set>  <item> <snapshot-id>snap-62a6700a</snapshot-id> </item> </snapshot-set> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Snapshots operation. Sample adapter response for the Describe Snapshots operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeSnapshotsResponse> <requestId>64fda38a-6fd4-4ccf-a592-a5eaec156da5</requestId> <snapshotSet> <item> <snapshotId>snap-62a6700a</snapshotId> <volumeId>vol-679d280e</volumeId> <status>completed</status> <startTime>2010-04-20T08:06:25.000Z</startTime> <progress>100%</progress> <ownerId>622872856407</ownerId> <volumeSize>1</volumeSize> <description>Test Description</description> </item> </snapshotSet> </DescribeSnapshotsResponse> </amazon-ec2-response>
Request and response for the Delete Snapshot operation

The Delete Snapshot operation enables you to delete a snapshot of an Amazon EBS snapshot that you own. The following figure shows a sample <items> XML element for the Delete Snapshot operation. Sample <items> XML element for the Delete Snapshot operation
143
<items> <item> <parameters> <snapshot-id></snapshot-id> </parameters> </item> </items>
The following table shows adapter request elements for the Delete Snapshot operation. Adapter request elements for the Delete Snapshot operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <snapshot-id>
Contains the name of the operation: delete-snapshot
Yes
Specifies the ID of the Amazon EBS snapshot that Yes you want to delete
144
The following figure shows a sample adapter request for the Delete Snapshot operation. Sample adapter request for the Delete Snapshot operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>delete-snapshot</operation-name> <parameters> <snapshot-id>snap-62a6700a</snapshot-id> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Delete Snapshot operation. Sample adapter response for the Delete Snapshot operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DeleteSnapshotResponse> <requestId>10a0ed9e-61dc-46e4-8e55-d812d641f62c</requestId> <return>true</return> </DeleteSnapshotResponse> </amazon-ec2-response>
Request and response for the Describe Snapshot Attribute operation

The Describe Snapshot Attribute operation returns information about an attribute of an Amazon EBS snapshot. You can specify only one attribute per call. The following figure shows a sample <items> XML element for the Describe Snapshot Attribute operation. Sample <items> XML element for the Describe Snapshot Attribute operation
145
<items> <item> <parameters> <snapshot-id></snapshot-id> <create-volume-permission/> </parameters> </item> </items>
The following table shows adapter request elements for the Describe Snapshot Attribute operation. Adapter request elements for the Describe Snapshot Attribute operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name>
Contains the name of the operation: describe-snapshot-attribute
Yes
146
<snapshot-id> <query-parameter>
Specifies the ID of the Amazon EBS snapshot whose attribute is to be described Specifies the parameter to query for the specified snapshot Valid value: create-volume-permission
Yes Yes
The following figure shows a sample adapter request for the Describe Snapshot Attribute operation. Sample adapter request for the Describe Snapshot Attribute operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-snapshot-attribute</operation-name> <parameters> <snapshot-id>snap-62a6700a</snapshot-id> <create-volume-permission/> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Snapshot Attribute operation. Sample adapter response for the Describe Snapshot Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeSnapshotAttributeResponse> <requestId>c0ad25d3-af58-4e61-9da3-2e154a01942e</requestId> <snapshotId>snap-62a6700a</snapshotId> <createVolumePermission> <item> <group>all</group> </item> <item> <userId>622872856407</userId> </item> </createVolumePermission> </DescribeSnapshotAttributeResponse> </amazon-ec2-response>
Request and response for the Modify Snapshot Attribute operation
147
The Modify Snapshot Attribute operation adds or removes permission settings for a specified snapshot. The following figure shows a sample <items> XML element for the Modify Snapshot Attribute operation. Sample <items> XML element for the Modify Snapshot Attribute operation
<items> <item> <parameters> <snapshot-id></snapshot-id> <create-volume-permission>  <add>  <item>  <user-id></user-id> </item> </add> </create-volume-permission> </parameters> </item> </items>
The following table shows adapter request elements for the Modify Snapshot Attribute operation. Adapter request elements for the Modify Snapshot Attribute operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
148
Specifies the mode for signing the adapter request Conditional: Required if not specified in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data>
<operation-name> <snapshot-id>
Contains the name of the operation: modify-snapshot-attribute
Yes
Specifies the ID of the Amazon EBS snapshot that No you want to modify No
<create-volume-permission> Specifies the create volume permission for the Amazon EBS snapshot that you want to modify add: Adds permission remove: Removes permission user-id: Specifies the user ID of a user who can create volumes from the snapshot group: Specifies the group that is allowed to create volumes from the snapshot (Currently, supports all.)
The following figure shows a sample adapter request for the Modify Snapshot Attribute operation. Sample adapter request for the Modify Snapshot Attribute operation
149
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>modify-snapshot-attribute</operation-name> <parameters> <snapshot-id>snap-62a6700a</snapshot-id> <create-volume-permission>  <add>  <item>  <user-id>622872856407</user-id> </item> </add> </create-volume-permission> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Modify Snapshot Attribute operation. Sample adapter response for the Modify Snapshot Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ModifySnapshotAttributeResponse> <requestId>4f60de8a-af64-44dd-9517-c5b6e8ea6407</requestId> <return>true</return> </ModifySnapshotAttributeResponse> </amazon-ec2-response>
Request and response for the Describe Volumes operation

The Describe Volumes operation describes the specified Amazon EBS volumes that you own. If you do not specify one or more volume IDs, this operation describes all the volumes that you own. The following figure shows a sample <items> XML element for the Describe Volumes operation. Sample <items> XML element for the Describe Volumes operation
150
<items> <item> <parameters> <volume-set>  <item> <volume-id></volume-id> </item> </volume-set> </parameters> </item> </items>
The following table shows adapter request elements for the Describe Volumes operation. Adapter request elements for the Describe Volumes operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
151
<operation-name> <volume-set> <volume-id>
Contains the name of the operation: describe-volumes Specifies the set of Amazon EBS volumes to be described Specifies the ID of the Amazon EBS volume to be described
Yes No No
The following figure shows a sample adapter request for the Describe Volumes operation. Sample adapter request for the Describe Volumes operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-volumes</operation-name> <parameters> <volume-set>  <item> <volume-id>vol-e14fec88</volume-id> </item> </volume-set> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Volumes operation.
152
Sample adapter response for the Describe Volumes operation

<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeVolumesResponse> <requestId>ec0fd56d-b878-45b4-8d03-09e42e024cdb</requestId> <volumeSet> <item> <volumeId>vol-e14fec88</volumeId> <size>15</size> <snapshotId>snap-cfa2b8a6</snapshotId> <availabilityZone>us-east-1a</availabilityZone> <status>available</status> <createTime>2010-03-31T08:14:49.000Z</createTime> <attachmentSet/> </item> </volumeSet> </DescribeVolumesResponse> </amazon-ec2-response>
Request and response for the Attach Volume operation

The Attach Volume operation attaches an Amazon EBS volume to a running instance and exposes the instance as the specified device. The following figure shows a sample <items> XML element for the Attach Volume operation. Sample <items> XML element for the Attach Volume operation
<items> <item> <parameters> <volume-id></volume-id> <instance-id></instance-id> <device></device> </parameters> </item> </items>
The following table shows adapter request elements for the Attach Volume operation. Adapter request elements for the Attach Volume operation Element Definition Required
153
<wsdl-location>
<endpoint-address>
<operation-name> <volume-id>
Contains the name of the operation: attach-volume Specifies the ID of the Amazon EBS volume The volume and instance must be within the same Availability Zone and the instance must be running. Specifies the ID of the instance to which the volume attaches The volume and instance must be within the same Availability Zone and the instance must be running. Specifies how the device is exposed to the instance (For example, /dev/sdh)
Yes Yes
<instance-id>
Yes
<device>
Yes
The following figure shows a sample adapter request for the Attach Volume operation. Sample adapter request for the Attach Volume operation
154
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>attach-volume</operation-name> <parameters> <parameters> <volume-id>vol-fd56fc94</volume-id> <instance-id>i-5bc8a930</instance-id> <device>/dev/sda2</device> </parameters> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Attach Volume operation. Sample adapter response for the Attach Volume operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <AttachVolumeResponse> <requestId>932e3043-8ed3-4578-8d76-e337abecb881</requestId> <volumeId>vol-fd56fc94</volumeId> <instanceId>i-5bc8a930</instanceId> <device>/dev/sda2</device> <status>attaching</status> <attachTime>2010-04-16T09:29:51.000Z</attachTime> </AttachVolumeResponse> </amazon-ec2-response>
Request and response for the Detach Volume operation

The Detach Volume operation detaches an Amazon EBS volume from an instance. The following figure shows a sample <items> XML element for the Detach Volume operation. Sample <items> XML element for the Detach Volume operation
155
<items> <item> <parameters> <volume-id></volume-id>  <instance-id></instance-id>  <device></device>  <force></force> </parameters> </item> </items>
The following table shows adapter request elements for the Detach Volume operation. Adapter request elements for the Detach Volume operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
156
<operation-name> <volume-id> <instance-id> <device> <force>
Contains the name of the operation: detach-volume Specifies the ID of the Amazon EBS volume that you want to detach Specifies the ID of the instance from which the volume is detached Specifies the name of the device Forces detachment if the previous detachment attempt did not occur cleanly (logging into an instance, unmounting the volume, and detaching normally) Note This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches nor file system meta data. If you use this option, you must perform file system check and repair procedures.
Yes Yes No No No
The following figure shows a sample adapter request for the Detach Volume operation. Sample adapter request for the Detach Volume operation
157
amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>detach-volume</operation-name> <parameters> <volume-id>vol-e14fec88</volume-id>  <instance-id>i-e577f48e</instance-id>  <device>/dev/sdh</device>  <force>true</force> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Detach Volume operation. Sample adapter response for the Detach Volume operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DetachVolumeResponse> <requestId>3e1d2401-c665-4547-b5d0-fccc29f5c961</requestId> <volumeId>vol-e14fec88</volumeId> <instanceId>i-e577f48e</instanceId> <device>/dev/sdh</device> <status>detaching</status> <attachTime>2010-03-31T08:25:25.000Z</attachTime> </DetachVolumeResponse> </amazon-ec2-response>
Request and response for the Reset Snapshot Attribute operation

The Reset Snapshot Attribute operation resets the permission settings for a specified snapshot. The following figure shows a sample <items> XML element for the Reset Snapshot Attribute operation. Sample <items> XML element for the Reset Snapshot Attribute operation
158
<items> <item> <parameters> <snapshot-id></snapshot-id> <create-volume-permission/> </parameters> </item> </items>
The following table shows adapter request elements for the Reset Snapshot Attribute operation. Adapter request elements for the Reset Snapshot Attribute operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name>
Contains the name of the operation: reset-snapshot-attribute
Yes
159
<snapshot-id> <reset parameter>
Specifies the ID of the Amazon EBS snapshot that Yes you want to reset Specifies the parameter that you want to reset for the specified snapshot Valid values: create-volume-permission Yes
The following figure shows a sample adapter request for the Reset Snapshot Attribute operation. Sample adapter request for the Reset Snapshot Attribute operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>reset-snapshot-attribute</operation-name> <parameters> <snapshot-id>snap-62a6700a</snapshot-id> <create-volume-permission/> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Reset Snapshot Attribute operation. Sample adapter response for the Reset Snapshot Attribute operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <ResetSnapshotAttributeResponse> <requestId>790bb430-bc8a-4964-a57e-5e1867a1bfb5</requestId> <return>true</return> </ResetSnapshotAttributeResponse> </amazon-ec2-response>
Request and response for the Delete Volume operation

The Delete Volume operation enables you to delete an Amazon EBS volume that you own. The following figure shows a sample <items> XML element for the Delete Volume operation. Sample <items> XML element for the Delete Volume operation
160
<items> <item> <parameters> <volume-id></volume-id> </parameters> </item> </items>
The following table shows adapter request elements for the Delete Volume operation. Adapter request elements for the Delete Volume operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name>
Contains the name of the operation: delete-volume
Yes
161
<volume-id>
Specifies the ID of the Amazon EBS volume to delete Note The volume remains in the deleting state for several minutes after entering this command.
Yes
The following figure shows a sample adapter request for the Delete Volume operation. Sample adapter request for the Delete Volume operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>delete-volume</operation-name> <parameters> <volume-id>vol-f354fe9a</volume-id> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Delete Volume operation. Sample adapter response for the Delete Volume operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DeleteVolumeResponse> <requestId>f5279ce1-e2c0-4f26-b7f4-5e931186ba11</requestId> <return>true</return> </DeleteVolumeResponse> </amazon-ec2-response>
Adapter requests and responses for the Windows operations

This section illustrates the adapter request and response for the Windows operations.
Request and response for the Cancel Bundle Task operation

The Cancel Bundle Task operation cancels an Amazon EC2 bundling operation.
162
The following figure shows a sample <items> XML element for the Cancel Bundle Task operation. Sample <items> XML element for the Cancel Bundle Task operation
<items> <item> <parameters> <bundle-id></bundle-id> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Cancel Bundle Task operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
163
<operation-name> <bundle-id>
Contains the name of the operation: cancel-bundle-task Specifies the ID of the bundle task to cancel
Yes Yes
The following figure shows a sample adapter request for the Cancel Bundle Task operation. Sample adapter request for the Cancel Bundle Task operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>cancel-bundle-task</operation-name> <parameters> <bundle-id>bun-bb1ffbd2</bundle-id> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Cancel Bundle Task operation. Sample adapter response for the Cancel Bundle Task operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CancelBundleTaskResponse> <requestId>f6e137bd-3ed5-4f33-abb2-d8c53568cabc</requestId> <bundleInstanceTask> <instanceId>i-91462efa</instanceId> <bundleId>bun-bb1ffbd2</bundleId> <state>cancelling</state> <startTime>2010-04-20T06:33:57.000Z</startTime> <updateTime>2010-04-20T06:37:04.000Z</updateTime> <storage> <S3> <bucket>kbundle</bucket> <prefix>kbundle</prefix> </S3> </storage> </bundleInstanceTask> </CancelBundleTaskResponse> </amazon-ec2-response>
Request and response for the Describe Bundle Tasks operation

164
The Describe Bundle Tasks operation describes the current bundling tasks. Bundling enables AMIs to become the basic unit of deployment that allow you to rapidly boot new custom instances as you need them. The following figure shows a sample <items> XML element for the Describe Bundle Tasks operation. Sample <items> XML element for the Describe Bundle Tasks operation
<items> <item> <parameters> <bundles-set>  <item> <bundle-id></bundle-id> </item> </bundles-set> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Describe Bundle Tasks operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
165
<operation-name> <bundles-set>
Contains the name of the operation: describe-bundle-tasks Specifies the set of bundle tasks to be described
Yes Yes
The following figure shows a sample adapter request for the Describe Bundle Tasks operation. Sample adapter request for the Describe Bundle Tasks operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-bundle-tasks</operation-name> <parameters> <bundles-set> <item> <bundle-id>bun-bb1ffbd2</bundle-id> </item> </bundles-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Describe Bundle Tasks operation. Sample adapter response for the Describe Bundle Tasks operation
166
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeBundleTasksResponse> <requestId>1def3bdc-b523-452f-a656-4ff6c770db66</requestId> <bundleInstanceTasksSet> <item> <instanceId>i-91462efa</instanceId> <bundleId>bun-bb1ffbd2</bundleId> <state>bundling</state> <startTime>2010-04-20T06:33:57.000Z</startTime> <updateTime>2010-04-20T06:34:18.000Z</updateTime> <storage> <S3> <bucket>kbundle</bucket> <prefix>kbundle</prefix> </S3> </storage> <progress>3%</progress> </item> </bundleInstanceTasksSet> </DescribeBundleTasksResponse> </amazon-ec2-response>
Request and response for the Bundle Instance operation

The Bundle Instance operation bundles a Windows instance. During bundling, only the root store is bundled. Data on other instance stores is not preserved. This procedure is not applicable to Linux, UNIX, or Windows instances that use Amazon EBS volumes as their root devices. The following figure shows a sample <items> XML element for the Bundle Instance operation. Sample <items> XML element for the Bundle Instance operation
<items> <item> <parameters> <instance-id></instance-id> <storage> <S3> <bucket></bucket> <prefix></prefix> <aws-access-key-id></aws-access-key-id> <secret-access-key></secret-access-key> <expiration-time></expiration-time> </S3> </storage> </parameters> </item> </items>
167
The following table describes the adapter request elements for this request. Adapter request elements for the Bundle Instance operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <bundle-id> <bucket>
Contains the name of the operation: bundle-instance Specifies the ID of the instance to bundle Specifies the bucket in which the AMI must be stored You can specify a bucket that you already own or a new bucket that Amazon EC2 creates on your behalf. If you specify a bucket that belongs to someone else, Amazon EC2 returns an error.
Yes Yes Yes
<prefix> <aws-access-key-id>
Specifies the beginning of the file name of the AMI Yes Specifies the Access Key ID of the owner of the Amazon S3 bucket Yes
168
<secret-access-key> <expiration-time>
Specifies the account's secret access key to sign the upload policy Specifies the expiration time of the upload policy Best practice BMC recommends that you set the expiration-time to 12 hours or more.
Yes Yes
The following figure shows a sample adapter request for the Bundle Instance operation. Sample adapter request for the Bundle Instance operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>bundle-instance</operation-name> <parameters> <instance-id>i-3d785856</instance-id> <storage> <S3> <bucket>kbundle</bucket> <prefix>testbundle</prefix> <aws-access-key-id>AKAAAAAJC5TERHT6ZQ</aws-access-key-id> <secret-access-key>+9YtuhaaaaaxkgsJUqOoIBUDwp5bOeR </secret-access-key> <expiration-time>10</expiration-time> </S3> </storage> </parameters> </amazon-ec2-request>
Note Based on the parameters that you provide in the <items> XML element, the adapter creates the signature and time-stamp security related elements.
The following figure shows the response for the sample adapter request for the Bundle Instance operation. Sample adapter response for the Bundle Instance operation
169
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CancelBundleTaskResponse> <requestId>f6e137bd-3ed5-4f33-abb2-d8c53568cabc</requestId> <bundleInstanceTask> <instanceId>i-91462efa</instanceId> <bundleId>bun-bb1ffbd2</bundleId> <state>cancelling</state> <startTime>2010-04-20T06:33:57.000Z</startTime> <updateTime>2010-04-20T06:37:04.000Z</updateTime> <storage> <S3> <bucket>kbundle</bucket> <prefix>kbundle</prefix> </S3> </storage> </bundleInstanceTask> </CancelBundleTaskResponse> </amazon-ec2-response>
Request and response for the Get Password Data operation

The Get Password Data operation enables you to retrieve the administrator password for the instances that are running Microsoft Windows operating systems. The following figure shows a sample <items> XML element for the Get Password Data operation. Sample <items> XML element for the Get Password Data operation
<items> <item> <parameters> <instance-id></instance-id>  <key-data></key-data> <key-file></key-file> </parameters> </item> </items>
The following table describes the adapter request elements for this request. Adapter request elements for the Get Password Data operation Element Definition Required
170
<wsdl-location>
<endpoint-address>
<operation-name> <instance-id> <key-data>
Contains the name of the operation: get-password-data
Yes
Specifies the ID of the instance for which you want Yes to retrieve the password Specifies the private key data using which the Windows instance is launched The private key data is used to decrypt the password. The key data is enclosed within BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY. Specifies the private key file using which the Windows instance is launched The private key file is used to decrypt the password. No
<key-file>
No
The following figure shows a sample adapter request for the Get Password Data operation. Sample adapter request for the Get Password Data operation
171
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>get-password-data</operation-name> <parameters> <instance-id>i-6448440c</instance-id> <key-file>C:\EC2\userkeys.pem</key-file> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample adapter request for the Get Password Data operation, when the private key is specified in the input for decrypting the password. Sample adapter response for the Get Password Data operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <GetPasswordDataResponse> <requestId>97dc3aa8-61fa-49d5-8111-906ab6d1c6f5</requestId> <instanceId>i-6448440c</instanceId> <timestamp>2010-01-27T08:16:41.000Z</timestamp> <passwordData>065xPMCsOf</passwordData> </GetPasswordDataResponse> </amazon-ec2-response>
The following figure shows the response for the sample adapter request for the Get Password Data operation, when the private key is not specified in the input. Sample adapter response for the Get Password Data operation when the private key is not specified in the input
172
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <GetPasswordDataResponse> <requestId>b9e163fa-b445-4117-b81b-9c13de191f9c</requestId> <instanceId>i-6448440c</instanceId> <timestamp>2010-01-27T08:16:41.000Z</timestamp> <passwordData>Vvyx7lZUUVsjNvmaShQ1cH6cwBZYjyq6JK1hZS8krWrwLj /HftPfDs/+bNW6VIvuFUg2o9KsctsKbe2ZymjSKuc6+AYAN2x2ZCtzAszkwUz3Ppj23 udoh5gwg7UtG34nbjRX0VUXJdj2OSnYg4q+pRH7SLH481n08IU9ipad26yHTa8npaYv 0PhheIEmqyHHTYoY7f91NcdM+EnerG+c8JnWVWiXyn98Xlvo4q8SNXRHbFsGevCHgt QHGNdy1TIZyhG7Qxgj7D6bqB89aXPuJFvqMswsrpb3mxJ1ESoN37YeJO8xGz6t4oVh 8X2I7nG2uBFEDMOt460sKUfm7YKgRA==</passwordData> </GetPasswordDataResponse> </amazon-ec2-response>
Adapter request and response for the Regions and Availability Zones operations
This section illustrates the adapter request and response for the Regions and Availability Zones operations.
Request and response for the Describe Availability Zones operation

The Describe Availability Zones operation displays the Availability Zones that are currently available to the account and their states. If you do not specify a value for the <availability-zone-set> element, this operation queries and returns all the available zones. The following figure shows a sample <items> XML element for the Describe Availability Zones operation. Sample <items> XML element for the Describe Availability Zones operation
<items> <item> <parameters> <availability-zone-set>  <item> <zone-name></zone-name> </item> </availability-zone-set> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Availability Zones operation Element Definition Required
173
<wsdl-location>
<endpoint-address>
Specifies the mode for signing the adapter request Conditional: Required if not specified in the configuration If <signature-properties mode = "key-files">, requires <private-key-file> and <certificate-file> If <signature-properties mode = "key-data">, requires <private-key-data> and <certificate-data>
<operation-name>
Contains the name of the operation: describe-availability-zones
Yes No No
<availability-zone-set> Specifies the set of zones to query <zone-name> Specifies the name of the zone to query
The following figure shows a sample adapter request for the Describe Availability Zones operation. Sample adapter request for the Describe Availability Zones operation
174
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-availability-zones</operation-name> <parameters> <availability-zone-set>  <item> <zone-name>us-east-1a</zone-name> </item> </availability-zone-set> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Availability Zones operation. Sample adapter response for the Describe Availability Zones operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeAvailabilityZonesResponse> <requestId>1ae50648-1d3a-4ef5-af3d-3ca1b46e0196</requestId> <availabilityZoneInfo> <item> <zoneName>us-east-1a</zoneName> <zoneState>available</zoneState> <regionName>us-east-1</regionName> <messageSet/> </item> </availabilityZoneInfo> </DescribeAvailabilityZonesResponse> </amazon-ec2-response>
Request and response for the Describe Regions operation

The Describe Regions operation describes regions that are currently available to the account. If you do not specify an item in region-set, all the available regions are queried and returned. The following figure shows a sample <items> XML element for the Describe Regions operation. Sample <items> XML element for the Describe Regions operation
175
<items> <item> <parameters> <region-set>  <item> <region-name></region-name> </item> </region-set> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Regions operation Element <wsdl-location> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
176
<region-set>
Specifies the set of regions to query
No
The following figure shows a sample adapter request for the Describe Regions operation. Sample adapter request for the Describe Regions operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-regions</operation-name> <parameters> <region-set>  <item> <region-name>us-east-1</region-name> </item> </region-set> </parameters> </amazon-ec2-request>
The following figure shows a sample adapter response for the Describe Regions operation. Sample adapter response for the Describe Regions operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeRegionsResponse> <requestId>c9074503-456a-43af-88fc-d96356cfaaba</requestId> <regionInfo> <item> <regionName>us-east-1</regionName> <regionEndpoint>ec2.us-east-1.amazonaws.com</regionEndpoint> </item> </regionInfo> </DescribeRegionsResponse> </amazon-ec2-response>
Adapter requests and responses for Key pair operations

This section illustrates the adapter requests and responses for Key pair operations.
Request and response for the Create Key Pair operation
177
The Create Key Pair operation enables you to create a new 2048-bit RSA key pair. For a key pair, Amazon EC2 stores the public key and the private key is displayed on the console. The Create Key Pair operation returns the private key in the form of an unencrypted PEM-encoded PKCS#8 private key. Note If a key with the specified name already exists in Amazon EC2, the operation returns an error in the adapter response.
The following figure shows a sample <items> XML element for the Create Key Pair operation. Sample <items> XML element for the Create Key Pair operation
<items> <item> <parameters> <key-name></key-name> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Create Key Pair operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
178
<operation-name> <key-name>
Contains the name of the operation: create-key-pair Specifies a unique name for the key pair
Yes Yes
The following figure shows a sample adapter request for the Create Key Pair operation. Sample adapter request for the Create Key Pair operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>create-key-pair</operation-name> <parameters> <key-name>Test API key</key-name> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Create Key Pair operation. Sample adapter response for the Create Key Pair operation
179
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <CreateKeyPairResponse> <requestId>21259841-adb2-48b4-80e5-62ea00b99fd7</requestId> <keyName>Test API key</keyName> <keyFingerprint>65:9f:db:76:e4:cd:29:ba:b1:c8:e3:12:fc:c7 :b1:14:4f:63:6c:1a</keyFingerprint> <keyMaterial> -----BEGIN RSA PRIVATE KEY----MIIEpAIBAAKCAQEA1Rw4lQKJZTFVgGj0esjaxTJgnu0zyE/9qJsRuc9wd2 vAbdP005bsN4LJa6zfipRHObv0wLzTrfeKKFilWqSuXrwvwj5MNCTojDHL UiIU9djojfXKYzQ6fPRQREZjHfgMr/gqASmR6CVU8ZlhPmsdak3iJ+mKmG GjULDQr+Z1fRiKtnpFzD12ZkQyJwElO7G2yMLq4sCTmsmaVlnnBM6mVia8 GXfwYJfaL2ft34SZ4bf/LW32LwZFN4OcjMZzB3F9LGA1kDd7RfwHUI2K9D c5HS/aLmkwNsXDNO/4x9jwdct02X0xCSNKaYCTl4XH938i3C4zcEs5yg1q phZD/mG92QIDAQABAoIBACriVvCFZiia2N3SQQBEUuHD1XWlvfndPuoi6l o9yB//6uUu9eFuSXKSOv4T95fnZr3TeNkgJminm4Gq9PtckEo4DFRGPQd xNeqgSo3oldczIvkOMP/tjqd+cniKwX9SXxs6ERnSx62zdXh4qPzqiSzPJ 2dos58eZsLiEdyTv6jAXYZ05usrZbBfcD/bsecf5DwjNkEnIkbk7CeNrgc xcbND4UHlmooq6ARXi/p9akXMBHFZuCztivLf+nSW7pjR5qeKbEFkQGs2dL 3qwrFjJ+i4Z3NqUVHqtt3F1RAOURbkETqC0tkdZ+ViWgreeC3pHJ+ 9YNBT51YauPAGWV96YEECgYEA7GsOJQZHsZAfmvRhrj97diiPGD6r+zUVwU 1HevMmaBA4nTa70rLoGagKEb0ntnVlR/Raq3EWfnkwxm9E4jbnoL8Ncbf SG9tmNGD12StOynlg+9E18g73W5rLK45UGIJvy2GRkUVwRaqSp24ni7pabD v3w79VII31chhh+yAJCbUCgYEA5sLzXHtf5RBu9rdmNIr3/hUSJ8/YlfNsMtz u6DVif97c333k8w4YYH6twHPdTPW2cqJ6JMyUFBIz1GVhM/RS5ctVBU4FNh5v n3L61kaU3AvFPLU3f8MZKbViUfaZjYq++CbbSr4udOQALjcGIAu8OtdNfIwkn YFQcDsaNQiDahUCgYEAosBgEGTuXfJVj5rE0+un1oO9XndmdZzpyRSmLKHOw rzH/JJ9YmL/HQptRCDvgc/3VT2GXZeQYKiVR0W6KfCaLDLZ0ns1DTBQ f6ZwGHyT1RcSCMjRVj2vU0SQsP9eLTE+PMiCKXuf+pWeN9zBJJO5 Q+FUg1DoDW0slsrqSLKZBjECgYEA3yuJGlbC/hAvkHD76jK/9b1BCrmrOBHs ASDD+FSwxwOszoO9qQZnsuKwfSBQ1L4JTcIuqGolh2e3MmE9aXaPuWc0 +WVkCtvSjf0v84zdKBZGERkc7HWtXzXpOWVpSYb2e51wlU9qNGfQ eOGEDffreWiBqsMKIj1Oosu147YxCaUCgYA7x4JgaAeelbXQSQrrGBAFnmbH WfokA36qmECnH9LdsuVbGkG4QSYGh7mC8uW9R8zXTkkK7Xus5NyGumLY53Sk hdeX3BF4jeomRom+Y9iBiDTUPTpV0yTGlzJCxBPb5LKrr418UHlN /Y63z47hW4q3io/F/vhC4Q99t5iOlxxwyA== -----END RSA PRIVATE KEY----</keyMaterial> </CreateKeyPairResponse> </amazon-ec2-response>
Request and response for the Delete Key Pair operation

The Delete Key Pair operation enables you to delete the specified key pair, by removing the public key from Amazon EC2. You can delete a key pair only if you own it. The following figure shows a sample <items> XML element for the Delete Key Pair operation. Sample <items> XML element for the Delete Key Pair operation
180
items> <item> <parameters> <key-name></key-name> </parameters> </item> </items>
The following table shows the elements for this adapter request. Adapter request elements for the Delete Key Pair operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
<operation-name> <key-name>
Contains the name of the operation: delete-key-pair Specifies the name of the key pair to be deleted
Yes Yes
181
The following figure shows a sample adapter request for the Delete Key Pair operation. Sample adapter request for the Delete Key Pair operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>delete-key-pair</operation-name> <parameters> <key-name>Test API key</key-name> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Delete Key Pair operation. Sample adapter response for the Delete Key Pair operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DeleteKeyPairResponse> <requestId>eba265ed-c00e-46b9-82e8-e8b6cb55236b</requestId> <return>true</return> </DeleteKeyPairResponse> </amazon-ec2-response>
Request and response for the Describe Key Pairs operation

The Describe Key Pairs operation enables you to retrieve information about key pairs available to you. If you specify the required key pairs, the operation returns information about the specified key pairs. If you do not specify any key pairs, the operation returns information about all registered key pairs available to you. The following figure shows a sample <items> XML element for the Describe Key Pairs operation. Sample <items> XML element for the Describe Key Pairs operation
182
<items> <item> <parameters> <key-set>  <item> <key-name>Test API key</key-name> </item> </key-set> </parameters> </item> </items>
The following table describes the elements for this adapter request. Adapter request elements for the Describe Key Pairs operation Element <wsdl-location>> Definition Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 Examples: http://ec2.amazonaws.com/doc/2009-11-30/ http://ec2.amazonaws.com/doc/2011-02-28/ Required Conditional: Required if not specified in the request If specified in the configuration and request, the value in the request overrides the value in the configuration No
<endpoint-address>
183
<operation-name> <key-set>
Contains the name of the operation: describe-key-pair Contains the key pairs with key names that you want to query
Yes Yes
The following figure shows a sample adapter request for the Describe Key Pairs operation. Sample adapter request for the Describe Key Pairs operation
<amazon-ec2-request> <wsdl-location>http://ec2.amazonaws.com/doc/2009-11-30/</wsdl-location> <endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address> <signature-properties mode = "key-files"> <private-key-file>C:\Security\ pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file> <certificate-file>C:\Security\ cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file> </signature-properties> <operation-name>describe-key-pairs</operation-name> <parameters> <key-set> <item> <key-name>Test API key</key-name> </item> </key-set> </parameters> </amazon-ec2-request>
The following figure shows the response for the sample Describe Key Pairs operation. Sample adapter response for the Describe Key Pairs operation
<amazon-ec2-response> <metadata> <status>success</status> </metadata> <DescribeKeyPairsResponse> <requestId>0cb7f039-9d3a-4bce-a1e8-3a991c9cc818</requestId> <keySet> <item> <keyName>Test API key</keyName> <keyFingerprint>65:9f:db:76:e4:cd:29:ba:b1:c8:e3:12:fc:c7:b1:14 :4f:63:6c:1a</keyFingerprint> </item> </keySet> </DescribeKeyPairsResponse> </amazon-ec2-response>
EBS Storage Locations

184
This chapter provides information about the EBS device name that you must use in various adapter requests.
Storage Locations
The following table describes how storage is exposed on the instance types. Location Definition Formatted and mounted as root ( / ) on all Linux and UNIX instance types Formatted and mounted as C: on all Windows instance types
/dev/sda1
/dev/sda2 or xvdb (Windows)
Formatted and mounted as /mnt on m1.small and c1.medium instances Formatted and mounted on small Windows instance types
/dev/sda3
Formatted and mounted as /swap on m1.small and c1.medium instances on all Linux and UNIX instance types Not available on Windows instances
/dev/sdb or xvdb (Windows)
Formatted and mounted as /mnt on m1.large, m1.xlarge, c1.xlarge, m2.xlarge, m2.2xlarge, and m2.4xlarge Linux and UNIX instances Formatted and mounted on m1.large, m1.xlarge, c1.xlarge, m2.xlarge, and m2.2xlarge Windows instances
/dev/sdc or xvdc (Windows)
Available on m1.large, m1.xlarge, and c1.xlarge Linux and UNIX instances Formatted and mounted on m1.large, m1.xlarge, c1.xlarge, and m2.4xlarge Windows instances
/dev/sdd or xvdd (Windows)
Available on m1.xlarge and c1.xlarge Linux and UNIX instances Formatted and mounted on m1.xlarge and c1.xlarge Windows instances
/dev/sde or xvde (Windows)
Available on m1.xlarge and c1.xlarge Linux and UNIX instances Formatted and mounted on m1.xlarge and c1.xlarge Windows instances
BMC Atrium Orchestrator Application Adapter for Amazon S3

Amazon S3 (Simple Storage Service) is an online storage web service offered by Amazon Web Services. Amazon S3 provides storage through web services interfaces, such as REST, SOAP, and so on.
185
S3's design aims to provide scalability, high availability, and low latency at commodity costs. S3 stores arbitrary objects up to five terabytes in size, each accompanied by up to two kilobytes of metadata. Objects are organized into buckets (each owned by an Amazon Web Services or AWS account), and identified within each bucket by a unique, user-assigned key. You can export Amazon Machine Images (AMIs) which are modified in the Elastic Compute Cloud (EC2) to S3 as bundles. You can create, list, and retrieve buckets and objects using either a Representational State Transfer (REST) HTTP interface or a Simple Object Access Protocol (SOAP) interface. Also, you can download objects using the HTTP GET interface and the BitTorrent protocol. Requests are authorized using an access control list (ACL) associated with each bucket and object. You choose bucket names and keys so that you can address objects using HTTP URLs. Because objects are accessible by unmodified HTTP clients, S3 can be used to replace significant existing (static) web hosting infrastructure. The Amazon AWS Authentication mechanism allows the bucket owner to create an authenticated URL with time-bounded validity. That is, someone can construct a URL that can be handed off to a third-party for access for a period such as the next thirty minutes, or the next twenty-four hours. The BMC Atrium Orchestrator Application Adapter for Amazon S3 executes operations on the Amazon S3 application server, using web service API calls. The actor adapter enables you to perform the following categories of operations in Amazon S3: Bucket operations Service operations Object operations
Configuring the BMC Atrium Orchestrator Application Adapter for Amazon S3

You configure an adapter in Grid Manager. The configuration specifies how the adapter interacts with Amazon S3. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view in Grid Manager provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when you configure an adapter. You can switch to the XML view to configure those elements and attributes that are not available as form fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration. The default name for the actor adapter is AmazonS3ActorAdapter.

If the default value for an optional element is acceptable, omit the element. Do not include empty elements. 1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. Access the adapters page by clicking the Manage tab; then click the Adapters tab. 3. In the Adapters in Repository list, select the adapter-bmc-amazon s3-actor check box to configure the actor adapter. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5.
186
5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or skip to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. The Name field does not support single-quote (') and ampersand (&) characters. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements, indicated with an asterisk *. 7. (optional) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements and attributes from the adapter user guide into the Properties text box, and then click OK. e. On the Warning message that appears, click Save. This action saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the node elements required for configuring the actor adapter: UI label Element Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Endpoint <endpoint-address> Address Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region Required? Conditional; required if not specified in the request No
<wsdl-location> WSDL Location
187
AWS Access Key ID
<aws-access-key-id> Specifies the 20-character public Access Key ID that is included in an Amazon Web Service (AWS) service request to identify the user AWS uses the Access Key ID to look up an account's Secret Access Key. Amazon.com then calculates a digital signature with the key. If they match, the user is considered authentic; otherwise, the authentication fails and the request is not processed.
Conditional; required if not specified in the request
Secret Access Key
<secret-access-key> Specifies the 40-character private identifier that is associated with the Access Key ID If you do not use the SOAP protocol with Web Service Security, a digital signature is calculated, using the Secret Access Key that you include in the request.
Conditional; required if not specified in the request
The following figure shows an XML sample for configuring the actor adapter without any configuration elements:
<config/>
The following figure shows an XML sample for configuring the actor adapter:
<config> <wsdl-location>http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl </wsdl-location> <endpoint-address>https://s3.amazonaws.com/soap</endpoint-address> <aws-access-key-id>SAMPLE_KEY</aws-access-key-id> <secret-access-key>SAMPLE_SECRET_KEY</secret-access-key> </config>
BMC Atrium Orchestrator Application Adapter for Amazon S3 module

Adapter_Actions directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3
The Adapter_Actions directory contains all the functional processes that are available in the v1.0 directory with simplified input values. The common inputs for these processes are as follows: adapter name wsdl location endpoint address aws access key id secret access key The functional processes in the Adapter_Actions directory internally invoke the relevant constructor processes in the Utilities directory.
188
Setup_Validation directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3
The processes in the Setup_Validation directory contain sample values for the request elements. You can change these sample values quickly to reflect the values in your environment. A process is provided to test each supported method of executing operations in Amazon S3.
Utilities directory for BMC Atrium Orchestrator Application Adapter for Amazon S3
v1.0 directory for the BMC Atrium Orchestrator Application Adapter for Amazon S3
The v1.0 directory contains functional processes specific to Amazon S3. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of operation.
BMC Atrium Orchestrator Application Adapter for Amazon S3 actor adapter requests and responses
The BMC Atrium Orchestrator actor adapter for Amazon S3 executes commands by using the web service on the Amazon S3 host. The adapter requests use a set of elements and an operation name. You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity. The actor adapter supports the following operations: Operation type Bucket_Operations Bucket_Operations Bucket_Operations Operation name List Bucket Contents Create Bucket Delete Bucket
Service_Operations List All My Buckets Object_Operations Object_operations Object_operations Put Object Inline Put Object Delete Object
Adapter requests and responses for the Bucket operations

This section illustrates the adapter requests and responses for the Bucket operations and describes the elements used in the requests.
189
Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Create Bucket operation

In Amazon S3, objects are organized into buckets, and the Create Bucket operation creates one of these buckets. Each bucket is owned by the Amazon Web Services account (or the AWS account). Each object is identified within each bucket by a unique, user-assigned key. You can create, list, and retrieve buckets and objects using either a Representational State Transfer (REST) HTTP interface or a Simple Object Access Protocol (SOAP) interface. The following figure shows the <items> XML element for the Create Bucket operation:
<items> <item> <parameters> <bucket>TestBucket</bucket> </parameters> </item> </items>
The following figure shows a sample adapter request for the Create Bucket operation:
<amazon-s3-request> <secret-access-key /> <operation-name>create-bucket</operation-name> <parameters> <bucket>TestBucket</bucket> </parameters> </amazon-s3-request>
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Required? Conditional; required if not specified in the configuration
190
<endpoint-address>
Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region
No
<aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user <secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> <bucket> Contains the name of the operation: create-bucket Specifies a name for the bucket that you want to create
Conditional; required if not specified in the configuration Conditional; required if not specified in the configuration Yes Yes
The following figure shows a sample adapter response for the Create Bucket operation:
<amazon-s3-response> <metadata> <status>success</status> </metadata> <CreateBucketResponse> <BucketName>TestBucket</BucketName> </CreateBucketResponse> </amazon-s3-response>
Delete Bucket operation

The Delete Bucket operation deletes the bucket specified in the Uniform Resource Identifier (URI). You must delete all the objects in the bucket, including the object versions and delete markers, before deleting the bucket. Only the owner of a bucket can delete it, regardless of the bucket's access control policy. The following figure shows the <items> XML element for the Delete Bucket operation:
191
<items> <item> <parameters> <bucket>TestBucket</bucket> </parameters> </item> </items>
The following figure shows a sample adapter request for the Delete Bucket operation:
<amazon-s3-request> <secret-access-key /> <operation-name>delete-bucket</operation-name> <parameters> <bucket>TestBucket</bucket> </parameters> </amazon-s3-request>
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for different regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region <aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user <secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> Contains the name of the operation: delete-bucket Conditional; required if not specified in the configuration Conditional; required if not specified in the configuration Yes Required? Conditional; required if not specified in the configuration No
<endpoint-address>
192
<bucket>
Specifies a name for the bucket that you want to delete
Yes
The following figure shows a sample adapter response for the Delete Bucket operation:
<amazon-s3-response> <metadata> <status>success</status> </metadata> <DeleteBucketResponse> <Code>204</Code> <Description>No Content</Description> </DeleteBucketResponse> </amazon-s3-response>
List Bucket Contents operation

The List Bucket Contents operation returns information about items in a specified bucket. The following figure shows the <items> XML element for the List Bucket Contents operation:
<items> <item> <parameters> <bucket>TestBucket</bucket> <prefix>l</prefix> <delimiter>/</delimiter> <max-keys>10</max-keys> <marker>Happy</marker> </parameters> </item> </items>
The following figure shows a sample adapter request for the List Bucket Contents operation:
<amazon-s3-request> <secret-access-key /> <operation-name>list-bucket-contents</operation-name> <parameters> <bucket>TestBucket</bucket> <prefix>l</prefix> <delimiter>/</delimiter> <max-keys>10</max-keys> <marker>Happy</marker> </parameters> </amazon-s3-request>
The following table describes the elements for the adapter request: Element Description Required?
193
<wsdl-location>
Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region
Conditional; required if not specified in the configuration No
<endpoint-address>
<aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user <secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID
Conditional; required if not specified in the configuration Conditional; required if not specified in the configuration Yes Yes No
<operation-name> <bucket> <prefix>
Contains the name of the operation:list-bucket-contents Specifies the name of the bucket whose contents you want to list Retrieves only those objects with key names that begin with the prefix string You can use prefixes to separate objects in a bucket into different sets of keys. Retrieves only those objects with key names that contain the delimiter string Specifies the maximum number of keys returned in the response body The server might return fewer than the specified number of keys, but not more. Indicates where in the bucket to begin listing The list includes only those keys that occur lexically after the marker. This is convenient for pagination; for example, to get the next page of results, use the last key of the current page as the marker.
<delimiter> <max-keys>
No No
<marker>
No
The following figure shows a sample adapter response for the List Bucket Contents operation:
194
<amazon-s3-response> <metadata> <status>success</status> </metadata> <ListBucketContentsResponse> <Name>TestBucket</Name> <Prefix>l</Prefix> <Marker>Happy</Marker> <MaxKeys>10</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>lg.txt</Key> <LastModified>2011-04-08T05:39:20.000Z</LastModified> <ETag>"8688c820caeaf6dfeb395755591d8f5e"</ETag> <Size>102</Size> <Owner> <ID>f7fd1a1bae4c700bf452ad628f5bc4787a52cca4d33bf2509b3364237143892d</ID> <DisplayName>invincible99</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <Contents> <Key>look.txt</Key> <LastModified>2011-04-13T07:04:47.000Z</LastModified> <ETag>"1c3d1d4f6d7b8d36c1bd7c3956ca3e9b"</ETag> <Size>756</Size> <Owner> <ID>f7fd1a1bae4c700bf452ad628f5bc4787a52cca4d33bf2509b3364237143892d</ID> <DisplayName>invincible99</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketContentsResponse> </amazon-s3-response>
Adapter requests and responses for the Object operations

This section illustrates the adapter requests and responses for the Object operations and describes the elements used in the requests. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Put Object Inline operation

The Put Object Inline operation adds an object whose size is 1 MB or smaller to a specified bucket. The following figure shows the <items> XML element for the Put Object Inline operation:
195
<items> <item> <parameters> <bucket>TestBucket</bucket> <key>create_oracle_instance.sql</key> <file-name>C:\\create_oracle_instance.sql</file-name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Put Object Inline operation:
<amazon-s3-request> <secret-access-key /> <operation-name>put-object-inline</operation-name> <parameters> <bucket>TestBucket</bucket> <key>create_oracle_instance.sql</key> <file-name>C:\\create_oracle_instance.sql</file-name> </parameters> </amazon-s3-request>
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region <aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user Conditional; required if not specified in the configuration Required? Conditional; required if not specified in the configuration No
<endpoint-address>
196
<secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> <bucket> <key> <file-name> Contains the name of the operation: put-object-inline Specifies the name of the bucket to which you want to add the object Specifies the key that you want to assign to the object Specifies the name of the file to be added to the bucket The file must be present on the peer where the adapter is enabled. The following figure shows a sample adapter response for the Put Object Inline operation:
<amazon-s3-response> <metadata> <status>success</status> </metadata> <PutObjectInlineResponse> <ETag>"bd80ff40107566c0a427a494a94a7377"</ETag> <LastModified>2011-04-18T08:40:57.000Z</LastModified> </PutObjectInlineResponse> </amazon-s3-response>
Conditional; required if not specified in the configuration Yes Yes Yes Yes
Delete Object operation

The Delete Object operation deletes the specified object from the specified bucket. The following figure shows the <items> XML element for the Delete Object operation:
<items> <item> <parameters> <bucket>TestBucket</bucket> <key>create_oracle_instance.sql</key> </parameters> </item> </items>
The following figure shows a sample adapter request for the Delete Object operation:
<amazon-s3-request> <secret-access-key /> <operation-name>delete-object</operation-name> <parameters> <bucket>TestBucket</bucket> <key>create_oracle_instance.sql</key> </parameters> </amazon-s3-request>
197
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region <aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user <secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> <bucket> <key> Contains the name of the operation: delete-object Specifies the name of the bucket from which you want to delete the object Specifies the key of the object that you want to delete Conditional; required if not specified in the configuration Conditional; required if not specified in the configuration Yes Yes Yes Required? Conditional; required if not specified in the configuration No
<endpoint-address>
The following figure shows a sample adapter response for the Delete Object operation:
<amazon-s3-response> <metadata> <status>success</status> </metadata> <DeleteObjectResponse> <Code>204</Code> <Description>No Content</Description> </DeleteObjectResponse </amazon-s3-response>
Put Object operation

The Put Object operation adds an object to the specified bucket. Unlike the Put Object Inline operation, the
198
Put Object operation does not have any restrictions on the size of the file being added to the bucket. The following figure shows the <items> XML element for the Put Object operation:
<items> <item> <parameters> <bucket>TestBucket</bucket> <key>PutObjectFile.mpg</key> <file-name>C:\TEMP\PutObjectFile.mpg</file-name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Put Object operation:
<amazon-s3-request> <operation-name>put-object</operation-name> <parameters> <bucket>TestBucket</bucket> <key>PutObjectFile.mpg</key> <file-name>C:\TEMP\PutObjectFile.mpg</file-name> </parameters> </amazon-s3-request>
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region <aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user Conditional; required if not specified in the configuration Required? Conditional; required if not specified in the configuration No
<endpoint-address>
199
<secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> <bucket> <key> <file-name> Contains the name of the operation: put-object Specifies the name of the bucket to which you want to add the object Specifies the key that you want to assign to the object Specifies the name of the file to be added to the bucket The file must be present on the peer where the adapter is enabled. The following figure shows a sample adapter response for the Put Object operation:
<amazon-s3-response> <metadata> <status>success</status> </metadata> <PutObjectResponse> <ETag>"3aa4369b5d760756a440773178c51612"</ETag> <LastModified>2011-06-07T05:46:08.000Z</LastModified> </PutObjectResponse> </amazon-s3-response>
Conditional; required if not specified in the configuration Yes Yes Yes Yes
Adapter requests and responses for the Service operation

This section illustrates the adapter requests and responses for the Service operation and describes the elements used in the request. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
List All My Buckets operation

The List All My Buckets operation returns a list of all the buckets owned by the sender of the request. Note Even if you specify the <endpoint-address> for a specific region, the List All My Buckets operation lists all the buckets in the various regions assigned to that user. The following figure shows the <items> XML element for the List All My Buckets operation:
<items> <item> <parameters> </parameters> </item> </items>
200
The following figure shows a sample adapter request for the List All My Buckets operation:
<amazon-s3-request> <secret-access-key /> <operation-name>list-all-my-buckets</operation-name> <parameters/> </amazon-s3-request>
The following table describes the elements for the adapter request: Element <wsdl-location> Description Specifies the target WSDL URL for Amazon S3 Example: http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.wsdl <endpoint-address> Specifies the web service endpoint to use for performing operations on Amazon S3 buckets across different regions Default: https://s3.amazonaws.com/soap: Endpoint in the US Standard region Values for regions: https://s3.amazonaws.com/soap: Endpoint in the US Standard region https://s3-us-west-1.amazonaws.com/soap: Endpoint in the US-West (Northern California) region https://s3-eu-west-1.amazonaws.com/soap: Endpoint in the EU (Ireland) region https://s3-ap-southeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Singapore) region https://s3-ap-northeast-1.amazonaws.com/soap: Endpoint in the Asia Pacific (Tokyo) region <aws-access-key-id> Specifies the 20-character public access key ID that is included in an Amazon Web Service (AWS) service request to identify the user <secret-access-key> Specifies the 40-character private identifier that is associated with the access key ID <operation-name> Contains the name of the operation: list-all-my-buckets Conditional; required if not specified in the configuration Conditional; required if not specified in the configuration Yes Required? Conditional; required if not specified in the configuration No
The following figure shows a sample adapter response for the List All My Buckets operation:
201
<amazon-s3-response> <metadata> <status>success</status> </metadata> <ListAllMyBucketsResponse> <Owner> <ID>f7fd1a1bae4c700bf452ad628f5bc4787a52cca4d33bf2509b3364237143892d</ID> <DisplayName>invincible99</DisplayName> </Owner> <Buckets> <Bucket> <Name>MakeMyBucket</Name> <CreationDate>2011-04-15T04:44:20.000Z</CreationDate> </Bucket> <Bucket> <Name>TestBucket</Name> <CreationDate>2011-04-07T09:37:05.000Z</CreationDate> </Bucket> <Bucket> <Name>bmc-bucket-5e2373e2-b660-45dc-9db6-fd3bbfe5c04d</Name> <CreationDate>2011-04-12T10:13:46.000Z</CreationDate> </Bucket> <Bucket> <Name>kaar</Name> <CreationDate>2011-04-12T09:11:43.000Z</CreationDate> </Bucket> </Buckets> </ListAllMyBucketsResponse> </amazon-s3-response>
BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB

The BMC Atrium Orchestrator Application Adapter for BMC Atrium Configuration Management Database (CMDB) interacts with the BMC Atrium CMDB. The BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB consists of an actor adapter, as well as the workflow processes to perform the standard applications actions available through the BMC Atrium CMDB API. The actor adapter for BMC Atrium CMDB provides operations that use the BMC Atrium CMDB API to extract or manipulate data in the CMDB application. The actor adapter can perform the following tasks: Adds one or more infrastructure elements to the BMC Atrium CMDB Deletes one or more infrastructure elements from the BMC Atrium CMDB Retrieve attributes for one or more infrastructure elements
Pre-requisites for the BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The following pre-requisites are applicable for the BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB.
202
The Atrium CMDB adapter communicates with the Atrium CMDB application through Web Services. The following components must be installed with the BMC Atrium CMDB application for the successful interaction of the adapter with the BMC Atrium CMDB application: Web Services infrastructure component Atrium Core Web Services component The adapter is certified on the following versions of BMC Atrium CMDB: version 7.5 Patch 003 version 7.6 version 7.6.03 Note If you want to configure the BMC Atrium CMDB version 7.6.03.00 with a BMC Atrium CMDB adapter, you need to use the CMDB Web Service version 2.0. For details about using the CMDB Web Service version 2.0, see Before you begin.
Configuring the BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the BMC Atrium CMDB application. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties.
Before you begin

To obtain the Web Service URL for the adapter configuration, perform the following steps: 1. Go to http://host:port/cmdbws/services/listServices to open the list of services for the Atrium Web Service. 2. Verify that the list of services contains "cmdbws" and that the Service Status is Active. 3. Copy the Web Service URL specified under the Service EPR heading (for example, http://host:port/cmdbws/server/cmdbws ). 4. Paste the URL into the Soap Url configuration element of your adapter configuration. Note You must only use the procedure when you want to use the CMDB Web Service version 2.0 to configure the BMC Atrium CMDB version 7.6.03.00 with a CMDB adapter. The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view, and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration. Note The BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB contains an actor adapter only; it does not include a monitor adapter. The default name for the actor adapter is BMCAtriumCMDBActorAdapter.

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2.
203
2. 3. 4. 5. 6.
Access the adapters page, by clicking the Manage tab; then click the Adapters tab. In the Adapters in Repository list, select the ro-adapter-bmc-atrium-cmdb-actor check box. Click Add to Grid to include the adapter in the Adapters on Grid list. Click Configure corresponding to the newly added adapter. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. The configuration elements for each adapter are described in that adapter's section. Include all required elements indicated with an asterisk (*). d. ( optional ) Click Switch to XML View and use the following steps to specify elements and attributes that are not in the form view. Note Switching to the XML view to specify those elements and attributes not included in the form means that you cannot thereafter use the form for modifying that configuration.
7. On the Warning message that appears, click Switch View. 8. In the Properties text box, use XML format to enter the configuration elements and attributes not available as fields in the form view. 9. Click OK. 10. (optional) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements from the adapter user guide into the Properties text box, and then click OK. Note If the default value for an optional element is acceptable, omit the element. Do not include empty elements. e. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the node elements required to configure the actor adapter.
Node elements required to configure the actor adapter UI label Soap Url Element <soap-url> Definition Specifies the URL for the remote SOAP service. The format of the URL is http://<host>:<port> for CMDB application 7.5 and 7.6 only. Specifies the version of the CMDB application to which the adapter communicates Valid values: v2.0 (default), v7.5, v7.6 Required Yes
Version
<version>
No
204
Patch
<patch>
Specifies the patch number of the BMC Atrium CMDB application to which the adapter communicates The patch number can be specified if the CMDB application uses out-of-box keystores for encryption and digital signature. Valid values: 001 and 003 Decides whether to install the SSL certificates Valid values: true, false (default) Specifies the Java standard Trust Key Store Pass Phrase Default value: changeit Indicates whether to include the wsse:Nonce (a randomly generated unique number) element in the wsse:UsernameToken Valid values: true, false (default) Indicates whether to include the wsse:Created element in the wsse:UsernameToken Valid values: true, false (default)
No
Install Certificate
<install-certificate>
No
Passphrase <passphrase>
No
Nonce Validation
<nonce-validation>
No
Created Validation
<created-validation>
No
Sign Request
<sign-request>
Indicates whether a SOAP No request should include a digital signature Valid values: true, false (default) Indicates whether a SOAP request should be encrypted Valid values: true, false (default) No
Encrypt Request
<encrypt-request>
Verify Reponse Signature
<verify-response-signature> Decides whether to verify the XML digital signature of the received SOAP response Valid values: true, false (default) <decrypt-response>
No
Decrypt Response
Decides whether to decrypt the No SOAP response Valid values: true, false (default) Contains the nodes to specify No the information about keystore, used for XML digital signature and decryption
None
205
None
<keystore-type>
Specifies the type of keystore Valid values: JKS, JCEKS, PCKS12 Only JKS has been tested with the application Default value: JKS Configures the adapter to use the keystore specified by the keystore filename It must contain the absolute path of the keystore file. Specifies the password of the keystore
No
None
<keystore-file>
No
None None
<keystore-password> <alias>
No
Specifies the name of the No asynchronous private key used by the adapter to sign its outgoing SOAP messages Specifies the password for the specified <alias> Contains the nodes used to specify information about the keystore, used for encryption and digital signature verification Specifies the name of the asynchronous public key used by the adapter to encrypt the SOAP requests Specifies the URL for the Atrium Instances Service No No
None None
<password> <encryption-properties>
None
<encryption-user>
No
Atrium Instances URL Atrium Instances WSDL Atrium Versions URL Atrium Versions WSDL
<atrium-instances-url >
Conditional; required with CMDB version 7.6.03 Conditional; required with CMDB version 7.6.03 Conditional; required with CMDB version 7.6.03
<atrium-instances-wsdl>
Specifies the WSDL location for the Atrium Instances Service Specifies the URL for the Atrium Versions Service
<atrium-versions-url>
<atrium-versions-wsdl>
Specifies the WSDL location CoConditional; for the Atrium Versions Service required with CMDB version 7.6.03nditional
The following figure shows an XML sample for configuring the adapter using the BMC Atrium CMDB 7.5 application with out-of-box keystores. XML template for configuring the actor adapter
206
<config> <soap-url></soap-url> <atrium-instances-url></atrium-instances-url> <atrium-instances-wsdl></atrium-instances-wsdl> <atrium-versions-url></atrium-versions-url> <atrium-versions-wsdl></atrium-versions-wsdl> <version></version> <patch></patch> <install-certificate></install-certificate> <passphrase></passphrase> <nonce-validation></nonce-validation> <created-validation></created-validation> <sign-request></sign-request> <encrypt-request></encrypt-request> <verify-reponse-signature></verify-reponse-signature> <decrypt-response></decrypt-response> <signature-properties> <keystore-type></keystore-type> <keystore-file></keystore-file> <keystore-password></keystore-password> <alias></alias> <password></password> </signature-properties> <encryption-properties> <keystore-type></keystore-type> <keystore-file></keystore-file> <keystore-password></keystore-password> <encryption-user></encryption-user> </encryption-properties> </config>
The following figure shows an XML sample for configuring the actor adapter using the BMC Atrium CMDB 7.5 application with out-of-box keystores. XML sample for configuring the actor adapter with out-of-box keystores
<config> <soap-url>http://abc-lt-01:9090</soap-url> <version>v7.5</version> <nonce-validation>true</nonce-validation> <created-validation>true</created-validation> <sign-request>true</sign-request> <encrypt-request>true</encrypt-request> <verify-reponse-signature>true</verify-reponse-signature> <decrypt-response>true</decrypt-response> </config>
The following figure shows an XML sample for configuring the adapter using the BMC Atrium CMDB 7.5 application (patch 001) with custom keystores. XML sample for configuring the adapter with custom keystores
207
<config> <soap-url>https://abc-lt-01:9090</soap-url> <version>v7.5</version> <patch>001</patch> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> <nonce-validation>true</nonce-validation> <created-validation>true</created-validation> <sign-request>true</sign-request> <encrypt-request>true</encrypt-request> <verify-reponse-signature>true</verify-reponse-signature> <decrypt-response>true</decrypt-response> <signature-properties> <keystore-type>jks</keystore-type> <keystore-file>D:\CMDB 7.5\security\cmdbwsclient.jks</keystore-file> <keystore-password>password</keystore-password> <alias>cmdb</alias> <password>mycmdb</password> </signature-properties> <encryption-properties> <keystore-type>jks</keystore-type> <keystore-file>D:\CMDB 7.5\security\cmdbwsserver.jks</keystore-file> <keystore-password>password</keystore-password> <encryption-user>cmdbserver</encryption-user> </encryption-properties> </config>
The following figure shows an XML sample for configuring the actor adapter for CMDB version 7.6.03 with default security settings. XML sample for configuring the actor adapter for CMDB version 7.6.03 with default security settings
<config> <soap-url>http://vm-xxx-abcd:1296</soap-url> <atrium-instances-url>https://vm-xxx- abcd:1297/atriumws7603/services /atrium_instances</atrium-instances-url> <atrium-instances-wsdl>http://vm-xxx- abcd:1296/atriumws7603/services /atrium_instances.wsdl</atrium-instances- wsdl> <atrium-versions-url>https://vm-xxx- abcd:1297/atriumws7603/services /atrium_versions</atrium-versions-url> <atrium-versions-wsdl>http://vm-xxx- abcd:1296/atriumws7603/services /atrium_versions.wsdl</atrium-versions-wsdl> <version>v7.6.03</version> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> </config>
The following figure shows an XML sample for configuring the actor adapter for CMDB version 7.6.03 with all security policies turned on. XML sample for configuring the actor adapter for CMDB version 7.6.03 with all security policies turned on
208
<config> <soap-url>http://vm-xxx-abcd:1296</soap-url> <atrium-instances-url>https://vm-xxx- abcd:1297/atriumws7603/services /atrium_instances</atrium-instances-url> <atrium-instances-wsdl>http://vm-xxx- abcd:1296/atriumws7603/services /atrium_instances.wsdl</atrium-instances-wsdl> <atrium-versions-url>https://vm-xxx- abcd:1297/atriumws7603/services /atrium_versions</atrium-versions-url> <atrium-versions-wsdl>http://vm-xxx- abcd:1296/atriumws7603/services /atrium_versions.wsdl</atrium-versions-wsdl> <version>v7.6.03</version> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> <nonce-validation>true</nonce-validation> <created-validation>true</created-validation> <sign-request>true</sign-request> <encrypt-request>true</encrypt-request> <verify-reponse-signature>true</verify-reponse-signature> <decrypt-response>true</decrypt-response> </config>
The following figure shows an XML sample for configuring the actor adapter using the BMC Atrium CMDB 2.0 application XML sample for configuring the actor adapter using BMC Atrium CMDB 2.0
<config> <soap-url>http://vm3-xxx-abcd:9090/cmdbws</soap-url> <version>v2.0</version> </config>
BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB module
The processes contained in the adapter module for the BMC Atrium Orchestrator adapter for BMC Atrium CMDB are used to execute basic operations to interface with BMC Atrium CMDB. These processes determine the version of BMC Atrium CMDB being used and call a process from the corresponding process directory. A process directory of v2.0, v7.5 are included in this module and contains processes specifically designed to interface with BMC Atrium CMDB 2.0, 7.5, and 7.6.
Top-level processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The top-level processes perform high-level functions and call specialized processes in the subdirectories of the version-specific directories. The top-level processes in the Project Explorer window execute the following version-specific BMC Atrium CMDB processes: [Create Items]
209
[Delete Items] [Find Items] [Update Items] [Get Versions] Note The <items> XML samples for the operations are different for different versions of BMC Atrium CMDB such as 2.0, 7.5, and 7.6. To obtain the <items> XML samples for BMC Atrium CMDB version 7.5 and later, see v7.5 - Configuration Item.
Create Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Create Items process creates CI or relationship instances within BMC Atrium CMDB. The following table describes the process input elements for the Create Items process. Process inputs - Create Items Process Description input adapter name version items Specifies the name of the adapter used for the process, configured in Grid Manager Default value: BMCAtriumCMDBActorAdapter Specifies the version of BMC Atrium CMDB system Valid values: v2.0, v7.5, v7.6 Specifies the XML document containing the elements required to create a CI or Relationship instance in BMC Atrium CMDB See the following figure for a sample XML document for a CI instance. See the following figure for sample XML documents for a Relationship instance. You must provide all the required attributes to create a record. Specifies the type of record to be created Valid value: configurationitem Required? No Yes Yes
item type
Yes
The following figure shows a sample <items> XML for the Create Items For CI Instance process. <items> XML sample for the Create Items For CI Instance process
210
<items> <class-type>CI</class-type> <item> <parameters> <username></username> <password></password> <login-info> <user-id>Demo</user-id> <password>Demo</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <attributes> <items> <name>Email</name> <value> <string-value>test@test.com</string-value> </value> </items> <items> <name>PersonDepartment</name> <value> <string-value>department</string-value> </value> </items> <items> <name>FirstName</name> <value> <string-value>test</string-value> </value> </items> <items> <name>LastName</name> <value> <string-value>test</string-value> </value> </items> <items> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </items> </attributes> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
The following figure shows a sample <items> XML for the Create Items For Relationship Instance process.
211
<items> XML sample for the Create Items For Relationship Instance process
<items> <class-type>Relationship</class-type> <item> <parameters> <login-info> <user-id>Demo</user-id> <password>Demo</password> <lang>English</lang> </login-info> <class-type>relationship</class-type> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Component</class-name> </class-name-id> <role1Name>Source</role1Name> <instance1Id>InsatanceId8610</instance1Id> <class1Id>BMC_DOCUMENT</class1Id> <role2Name>Destination</role2Name> <instance2Id>InsatanceId9610</instance2Id> <class2Id>BMC_DOCUMENT</class2Id> <a-dataset-id>BMC.SAMPLE</a-dataset-id> <attributes> <items> <name>AttributeDataSourceList</name> <value> <string-value>AttributeDataSourceList1</string-value> </value> </items> <items> <name>ShortDescription</name> <value> <string-value>na</string-value> </value> </items> <items> <name>InstanceId</name> <value> <string-value>RelationInstance1</string-value> </value> </items> <items> <name>AccountID</name> <value> <string-value>AccountID1</string-value> </value> </items> <items> <name>AssignedTo</name> <value> <string-value>AssignedTo1</string-value> </value> </items>
212
<items> <name>CMDBWriteSecurity</name> <value> <string-value>1;</string-value> </value> </items> <items> <name>Status</name> <value> <enum-value>1</enum-value> </value> </items> <items> <name>CMDBRowLevelSecurity</name> <value> <string-value>1;</string-value> </value> </items> <items> <name>Name</name> <value> <string-value>DocumentRelationone</string-value> </value> </items> <items> <name>ReconciliationIdentity</name> <value> <string-value>R1</string-value> </value> </items> <items> <name>Submitter</name> <value> <string-value>Demo</string-value> </value> </items> </attributes>
213
The following figure illustrates the adapter response for the Create Items For CI Instance process. Adapter response for the Create Items For CI Instanceprocess
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value /> </status> </parameters> </item> </bmc-atrium-cmdb-response>
Delete Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Delete Items process deletes CI or relationship instances within BMC Atrium CMDB. The following table describes the process input elements for the Delete Items process. Process inputs - Delete Items process Process Description input adapter name version items Specifies the name of the adapter used for the process, configured in Grid Manager Default value: BMCAtriumCMDBActorAdapter Specifies the version of BMC Atrium CMDB system Valid values: v2.0, v7.5, v7.6 Specifies the XML document containing the elements required to delete a record from BMC Atrium CMDB Records can be deleted based on an instance ID, instance name, or reconciliation identity. Specifies the type of record to be deleted Valid value: configurationitem Required? No Yes Yes
item type
Yes
The following figure shows a sample <items> XML for the Delete Items By Instance ID process. <items> XML sample for the Delete Items By Instance ID process
214
<items> <delete-criteria>InstanceId</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-9BAA6AF05C404E2DAF680027433193E5</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure illustrates the adapter response for the Delete Items By Instance ID process. Adapter response for the Delete Items By Instance ID process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
The following figure shows sample <items> XML for the Delete Items By Instance Name process. <items> XML sample for the Delete Items By Instance Name process
215
<items> <delete-criteria>InstanceName</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-name>Test_Instance_Name</instance-name> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure illustrates the adapter response for the Delete Items By Instance Name process. Adapter response for the Delete Items By Instance Name process
<bmc-atrium-cmdb-response> <item> <instance-id>InsatanceId9610</instance-id> <metadata> <status>success</status> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
The following figure shows a sample <items> XML for the Delete Items By Reconciliation Identity (ID) process. <items> XML sample for the Delete Items By Reconciliation Identity process
216
<items> <delete-criteria>ReconciliationIdentity</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <reconciliation-identity>OI9BAA6AF05C404E2DAF680027433193E5</reconciliation-identity> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure illustrates the adapter response for the Delete Items By Reconciliation ID process. Adapter response for the Delete Items By Reconciliation ID process
Find Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Find Items process retrieves CI and relationship instances from BMC Atrium CMDB. The following table describes the input elements for the Find Items process. Process inputs - Find Items Process input Description Required?
217
adapter name Specifies the name of the adapter used for the process, configured in Grid Manager Default value: BMCAtriumCMDBActorAdapter version items item type Specifies the version of BMC Atrium CMDB system Valid values: v2.0, v7.5, v7.6 Specifies the XML document containing the elements required to query BMC Atrium CMDB Specifies the type of record to be retrieved Valid values: configurationitem, graphquery
No Yes Yes Yes
Note The Find Items process gives a parsing exception if the '<' and '<=' relational operators are used.
The following figure shows a sample <items> XML for the Find Items With Selected Attributes process.
<items> XML sample for the Find Items With Selected Attributes process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <query><![CDATA[AccountID = NULL]]></query> <attributes> <items>Model</items> <items>AccountID</items> <items>OwnerName</items> </attributes> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <items> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </items> </sort-order> <a-dataset-id /> <a-get-mask>GET_MASK_NONE</a-get-mask> </parameters> </item> </items>
218
The following figure shows a sample <items> XML for the Find Items With All Attributes process. <items> XML sample for the Find Items With All Attributes process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <query><![CDATA[AccountID = NULL]]></query> <attributes/> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <items> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </items> </sort-order> <a-dataset-id /> <a-get-mask>GET_MASK_NONE</a-get-mask> </parameters> </item> </items>
The following figure illustrates the adapter response for the Find Items process. Adapter response for the Find Items process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error> Present only with a staus of 'error'</error> <item-count>2</item-count> </metadata> <parameters> <instance-info> <value> <element> <instance-id>AG4445535442002zkKRgKhCFHglU0B</instance-id> <instance-attributes> <element>
219
<name>Model</name> <value> <string-value>Model value 1</string-value> </value> </element> <element> <name>Account ID</name> <value> <string-value>Account ID 1</string-value> </value> </element> <element> <name>Owner Name</name> <value> <string-value>Owner 1</string-value> </value> </element> </instance-attributes> </element> <element> <instance-id>AG444553544200MToKRgI2GGHgz00B</instance-id> <instance-attributes> <element> <name>Model</name> <value> <string-value>Model value 2</string-value> </value> </element> <element> <name>Account ID</name> <value> <string-value>Account ID 2</string-value> </value> </element> <element> <name>Owner Name</name> <value> <string-value>Owner 2</string-value> </value> </element> </instance-attributes> </element> </value> </instance-info> <status> <value /> </status>
220
</parameters> </item> </bmc-atrium-cmdb-response>
Update Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
Updates specified attribute values for a CI or Relationship instance in BMC Atrium CMDB. The following table describes the process inputs for the Update Items process. Process inputs - Update Items process Process input adapter name version items item type Description Specifies the name of the adapter to be used for the process, configured in Grid Manager Default value: BMCAtriumCMDBActorAdapter Specifies the version of BMC Atrium CMDB system Valid values: v2.0, v7.5, v7.6 Specifies an XML document containing the attribute to update for a specified record in BMC Atrium CMDB Specifies the type of record to be updated Valid value: configuration item Required? No
Yes Yes Yes
The following figure shows a sample <items> XML for the Update Items process. <items> XML sample for the Update Items process
221
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <items> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </items> <items> <name>Availability</name> <value> <enum-value>High</enum-value> </value> </items> <items> <name>LastScanDate</name> <value> <time-value>03/02/2007 01:00:00 PM</time-value> </value> </items> </attributes> <instance-id>OI-7E0E3E02372A4D3E89B0A403D4239285</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
The following figure illustrates the adapter response for the Update Items process. Adapter response for the Update Items process
222
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
Get Versions process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Get Versions process retrieves details such as the major and minor versions of the BMC Atrium CMDB application and application ID. The following figure shows a sample <items> XML for the Get Versions process. <items> XML sample for the Get Versions process
<items> <item> <parameters> <cmdb-username>appadmin</cmdb-username> <cmdb-password/> <soap-username/> <soap-password/> <language/> <locale/> <time-zone/> <authentication/> </parameters> </item> </items>
The following table describes the process inputs for the Get Versions process. Process inputs - Get Versions process Process input Description Required? No
cmdb-username Specifies the user name for the authentication of BMC Atrium CMDB
cmdb-password Specifies the password that corresponds with the specified <cmdb-username> No soap-username soap-password language Specifies user name for the authentication of SOAP Specifies the password that corresponds to the specified <soap-username> Specifies the language used for BMC Atrium CMDB No No No
223
locale time-zone
Specifies the locale used for BMC Atrium CMDB Specifies the timezone used for BMC Atrium CMDB
No No
The following figure illustrates the adapter response for the Get Versions process with BMC Atrium CMDB 2.0. Adapter response for the Get Versions process with BMC Atrium CMDB 2.0
<bmc-atrium-cmdb-response> <metadata> <status>success</status> </metadata> <parameters> <version-info-list> <value> <element> <application-id>OB00C04FA081BABZlxQAmyflAg1wEA</application-id> <application-name>BMC Atrium CMDB</application-name> <maintenance-ver>1</maintenance-ver> <major-ver>2</major-ver> <minor-ver>0</minor-ver> <patch-num>0</patch-num> <is-exist>true</is-exist> <adapter-config-version>v2.0</adapter-config-version> </element> </value> </version-info-list> <status> <value /> </status> </parameters> </bmc-atrium-cmdb-response>
The following figure illustrates the adapter response for the Get Versions process with BMC Atrium CMDB 7.5 patch 003. Adapter response for the Get Versions process with BMC Atrium CMDB 7.5 patch 003
224
<bmc-atrium-cmdb-response> <metadata> <status>success</status> </metadata> <parameters> <extensions /> <version-info-list> <value> <element> <application-id>OB00C04FA081BABZlxQAmyflAg1wEA</application-id> <application-name>BMC Atrium CMDB</application-name> <maintenance-ver>0</maintenance-ver> <major-ver>7</major-ver> <minor-ver>5</minor-ver> <patch-num>3</patch-num> <is-exist>true</is-exist> <adapter-config-version>v7.5</adapter-config-version> </element> </value> </version-info-list> <status> <value /> </status> </parameters> </bmc-atrium-cmdb-response>
The following figure illustrates the adapter response for the Get Versions process with BMC Atrium CMDB 7.6. Adapter response for the Get Versions process with BMC Atrium CMDB 7.6
225
<bmc-atrium-cmdb-response> <metadata> <status>success</status> </metadata> <parameters> <extensions /> <version-info-list> <value> <element> <application-id>OB00C04FA081BABZlxQAmyflAg1wEA</application-id> <application-name>BMC Atrium CMDB</application-name> <maintenance-ver>0</maintenance-ver> <major-ver>7</major-ver> <minor-ver>6</minor-ver> <patch-num>0</patch-num> <is-exist>true</is-exist> <adapter-config-version>v7.6</adapter-config-version> </element> </value> </version-info-list> <status> <value /> </status> </parameters> </bmc-atrium-cmdb-response>
SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The processes in the SetupValidation directory contain sample values for the request elements. You can change these sample values quickly to reflect the values in your environment. A process is provided to test each supported method of executing operations in BMC Atrium CMDB. It must be noted that the process contains an XML for CMDB application version 2.0 only.
Utilities directory for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
Extract From Items process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Extract Element From Items process extracts the value of the element from the items input. You can use any element listed in the following table. List of Elements for Extract Element From Items process
226
<a-dataset-id> <class2Id> <delete-option> <instance-id> <query> <password>
<a-get-mask> <class-name-id> <first-retrieve> <instance-name>
<attributes> <class-type> <instance1Id> <login-info>
<class1Id> <delete-criteria> <instance2Id> <max-retrieve> <role2Name> <login-info>
<reconciliation-identity> <role1Name> <username> <sort-order>
<start-class-name-id> <start-extension-id> <on-match-proceed> <graph>
<start-instance-id> <direction> <a-get-mask> <a-dataset-id>
The following table describes the process inputs for the Extract Element From Items process. Process inputs - Extract Element From Items process Process input items Description Specifies an XML document provided by a higher level process from which data is extracted Required? No
The following table describes the process outputs for the Extract Element From Items process. Process output - Extract Element From Items process Process output Description items-output Specifies the value of <Element>
Set Default Adapter Name process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Set Default Adapter Name process sets the default name for the adapter used by the processes in the module if you do not provide the 'adapter name', input parameter. The following table describes the process inputs for Set Default Adapter Name process. Process inputs - Set Default Adapter Name process Process input Description adapter name Required
Specifies the name of the adapter used to handle the request No Default value: BMCAtriumCMDBActorAdapter
The following table describes the process outputs for the Set Default Adapter Name process. Process outputs - Set Default Adapter Name process Process output Description adapter name Specifies the default adapter name
227
Unsupported Class Type Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Unsupported Class Type Error process sets and debugs the error string if an unsupported or malformed <class-type> is provided for an input parameter. There are no defined inputs or outputs for this process.
Unsupported Delete Criteria Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Unsupported Delete Criteria Error process sets and debugs the error string if an unsupported <delete-criteria> is provided for deleting a CI or Relationship instance. There are no defined inputs or outputs for this process.
Unsupported Entity Error process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Unsupported Entity Error process sets and debugs the error string if an unsupported entity is provided for an input parameter. There are no defined inputs or outputs for this process.
Version Error Reporting process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Version Error Reporting process sets and debugs the error string if an unsupported version is provided for an input parameter. There are no defined inputs or outputs for this process.
ConfigurationItem - Create Instance process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The Configuration Item - Create Instance process creates an instance within BMC Atrium CMDB for the specified class. The following table describes the process inputs for the ConfigurationItem - Create Instance process. Process inputs - ConfigurationItem - Create Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information for an instance to be created in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the ConfigurationItem - Create Instance process. <items> XML sample for the ConfigurationItem - Create Instance process
228
<items> <class-type>CI</class-type> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <attributes> <items> <name>Attribute name 1</name> <value> <string-value>value for attribute name 1</string-value> </value> </items> </attributes> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
The following figure shows a sample <items> XML for the ConfigurationItem - Create Instance for Relationship process. <items> XML sample for the ConfigurationItem - Create Instance for Relationship process
229
<items> <class-type>Relationship</class-type> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <role1Name>Source</role1Name> <instance1Id>OI-8081A4AF60BD451EAB53C2550246CC4C</instance1Id> <class1Id>BMC_ACCOUNT</class1Id> <role2Name>Destination</role2Name> <instance2Id>OI-153F67CBFDB74210A689949D91F89F96</instance2Id> <class2Id>BMC_ACCOUNT</class2Id> <a-dataset-id>BMC.ASSET</a-dataset-id> <attributes> <items> <name>Attribute name 1</name> <value> <string-value>value for attribute name 1</string-value> </value> </items>
The following figure illustrates the adapter response for the ConfigurationItem - Create Instance for Relationship process. Adapter response for the ConfigurationItem - Create Instance for Relationship process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value/> </status> </parameters> </bmc-atrium-cmdb-response>
ConfigurationItem - Delete Instance process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
230
The ConfigurationItem - Delete Instance process deletes a CI or relationship instance using an instance ID within BMC Atrium CMDB. Process inputs - ConfigurationItem - Delete Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter XML document containing the information used to delete a specific instance in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the ConfigurationItem - Delete Instance By InstanceId process. <items> XML sample for the ConfigurationItem - Delete Instance By InstanceId process
<items> <delete-criteria>InstanceId</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-9BAA6AF05C404E2DAF680027433193E5</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure shows a sample <items> XML for the ConfigurationItem - Delete Instance By Instance Name process. <items> XML sample for the ConfigurationItem - Delete Instance By Instance Name process
231
<items> <delete-criteria>InstanceName</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-name>Test_Instance_Name</instance-name> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure shows a sample <items> XML for the ConfigurationItem - Delete Instance By Reconcilation Identity process. <items> XML sample for the ConfigurationItem - Delete Instance By Reconcilation Identity process
<items> <delete-criteria>ReconciliationIdentity</delete-criteria> <item> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <reconcilitation-identity>OI-9BAA6AF05C404E2DAF680027433193E5 </reconciliation-identity> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> <items>
The following figure illustrates the adapter response for the ConfigurationItem - Delete Instance process. Adapter response for the ConfigurationItem - Delete Instance process
232
<bmc-atrium-cmdb-response> <item> <instance-id>AG444553544200C18TRgPOE4EAZWEB</instance-id> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
v2.0 - ConfigurationItem processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The following processes are included in the v2.0 directory: [Create CI Instance process] [Create Relation Instance process] [Delete Instance By Instance Name process] [Delete Instance By InstanceId process] [Delete Instance By Reconciliation Identity process] [Find Instance process] [Update Instance process]
Create CI Instance process for v2.0

The Create CI Instance process creates a Configuration Item within BMC Atrium CMDB for the specified class. The following table describes the process inputs for the Create CI Instance process. Process inputs - Create CI Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the attribute for an instance to be created in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Create CI Instance process. <items> XML sample for the Create CI Instance process
233
<items> <class-type>CI</class-type> <item> <parameters> <username></username> <password></password> <login-info> <user-id>Demo</user-id> <password>Demo</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <attributes> <items> <name>Email</name> <value> <string-value>test@test.com</string-value> </value> </items> <items> <name>PersonDepartment</name> <value> <string-value>department</string-value> </value> </items> <items> <name>FirstName</name> <value> <string-value>test</string-value> </value> </items> <items> <name>LastName</name> <value> <string-value>test</string-value> </value> </items> <items> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </items> </attributes> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
The following figure illustrates the adapter response for the Create CI Instance process.
234
Adapter response for the Create CI Instance process

<bmc-atrium-cmdb-response> <item> <metadata> <status>Success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value/> </status> </parameters> </item> </bmc-atrium-cmdb-response>
Create Relation Instance process for v2.0

The Create Relation Instance process creates a relationship instance between two or more CI instances within BMC Atrium CMDB. The following table describes the process input elements for the Create Relation Instance process. Process inputs - Create Relation Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information for a relationship instance to be created in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Create Relation Instance process. <items> XML sample for the Create Relation Instance process
<items> <class-type>Relationship</class-type> <item> <parameters> <login-info> <user-id>Demo</user-id> <password>Demo</password> <lang>English</lang> </login-info> <class-type>relationship</class-type> <class-name-id> <namespace-name>BMC.CORE</namespace-name>
235
<class-name>BMC_Component</class-name> </class-name-id> <role1Name>Source</role1Name> <instance1Id>InsatanceId8610</instance1Id> <class1Id>BMC_DOCUMENT</class1Id> <role2Name>Destination</role2Name> <instance2Id>InsatanceId9610</instance2Id> <class2Id>BMC_DOCUMENT</class2Id> <a-dataset-id>BMC.SAMPLE</a-dataset-id> <attributes> <items> <name>AttributeDataSourceList</name> <value> <string-value>AttributeDataSourceList1</string-value> </value> </items> <items> <name>ShortDescription</name> <value> <string-value>na</string-value> </value> </items> <items> <name>InstanceId</name> <value> <string-value>RelationInstance1</string-value> </value> </items> <items> <name>AccountID</name> <value> <string-value>AccountID1</string-value> </value> </items> <items> <name>AssignedTo</name> <value> <string-value>AssignedTo1</string-value> </value> </items> <items> <name>CMDBWriteSecurity</name> <value> <string-value>1;</string-value> </value> </items> <items> <name>Status</name> <value> <enum-value>1</enum-value> </value> </items> <items> <name>CMDBRowLevelSecurity</name> <value> <string-value>1;</string-value>
236
</value> </items> <items> <name>Name</name> <value> <string-value>DocumentRelationone</string-value> </value> </items> <items> <name>ReconciliationIdentity</name> <value> <string-value>R1</string-value> </value> </items> <items> <name>Submitter</name> <value> <string-value>Demo</string-value> </value> </items> </attributes>
237
The following figure illustrates the adapter response for the Create Relation Instance process. Adapter response for the Create Relation Instance process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value/> </status> </parameters> </item> </bmc-atrium-cmdb-response>
Delete Instance By Instance Name process for v2.0

The Delete Instance By Instance Name process deletes a CI or relationship instances using an instance name within BMC Atrium CMDB. The following table describes the process inputs for the Delete Instance By Instance Name process. Process inputs - Delete Instance By Instance Name process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Delete Instance By Instance Name process. <items> XML sample for the Delete Instance By Instance Name process
238
<items> <item> <username>SOAP user name</username> <password>SOAP password</password> <parameter> <login-info> <user-id>BMCAtrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-name>Test_Instance_Name</instance-name> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By Instance Name process. Adapter response for the Delete Instance By Instance Name process
<bmc-atrium-cmdb-response> <item> <instance-id>InsatanceId9610</instance-id> <metadata> <status>success or error</status> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
Delete Instance By InstanceId process for v2.0

The Delete Instance By InstanceId process deletes a CI or relationship instance using an instance ID within BMC Atrium CMDB. The following table describes the process input elements for the Delete Instance by InstanceId process. Process inputs - Delete Instance By InstanceId process Process input adapter name Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Required? No
239
items
Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB
Yes
The following figure shows a sample <items> XML for the Delete Instance By InstanceId process. <items> XML sample for the Delete Instance By InstanceId process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <instance-id>OI-C5E85EDDDA3C486790756FC07C61394D</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By InstanceId process. Adapter response for the Delete Instance By InstanceId process
Delete Instance By Reconciliation Identity process for v2.0

The Delete Instance By Reconciliation Identity process deletes a CI or relationship instance using a reconciliation identity within BMC Atrium CMDB. The following table describes the process inputs for the Delete Instance By Reconciliation Identity process. Process inputs - Delete Instance By Reconciliation Identity process
240
Process input adapter name items
Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB
Required? No Yes
The following figure shows a sample <items> XML for the Delete Instance By Reconciliation Identity process. <items> XML sample for the Delete Instance By Reconciliation Identity process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <reconciliation-identity>1234</reconciliation-identity> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By Reconciliation Identity process. Adapter response for the Delete Instance By Reconciliation Identity process
Find Instance process for v2.0
241
The Find Instance process retrieves CI and relationship instances from BMC Atrium CMDB. The following table describes the process inputs the Find Instance process. Process inputs - Find Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information to retrieve records from BMC Atrium CMDB for a specified query Required? No Yes
The following figure shows a sample <items> XML for the Find Instance With Selected Attributes process . <items> XML sample for the Find Instance With Selected Attributes process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <query><![CDATA[AccountID = NULL]]></query> <attributes> <items>Model</items> <items>AccountID</items> <items>OwnerName</items> </attributes> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <items> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </items> </sort-order> <a-dataset-id /> <a-get-mask>GET_MASK_NONE</a-get-mask> </parameters> </item> </items>
The following figure shows a sample <items> XML for the Find Instance With All Attributes process.
242
<items> XML sample for the Find Instance With All Attributes process
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <query><![CDATA[AccountID = NULL]]></query> <attributes/> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <items> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </items> </sort-order> <a-dataset-id /> <a-get-mask>GET_MASK_NONE</a-get-mask> </parameters> </item> </items>
The following figure illustrates the adapter response for the Find Instance process. Adapter response for the Find Instance process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> <item-count>2</item-count> </metadata> <parameters> <instance-info> <value> <element> <instance-id>AG4445535442002zkKRgKhCFHglU0B</instance-id> <instance-attributes> <element> <name>Destination.ReconciliationIdentity</name> <value> <string-value>P3</string-value>
243
</value> </element> <element> <name>Destination.DatasetId</name> <value> <string-value>BMC.ASSET</string-value> </value> </element> <element> <name>ClassId</name> <value> <keyword value-value>Value</keyword-value> </value> </element> <element> <name>Source.ClassId</name> <value> <enum-value>Enum value</enum-value> </value> </element> . . . </instance-attributes> </element> <element> <instance-id>AG4445535442002zkKRgI2GGHgz00B</instance-id> <instance-attributes> <element> <name>Destination.ReconciliationIdentity</name> <value> <string-value>P3</string-value> </value> </element> <element> <name>Destination.DatasetId</name> <value> <string-value>BMC.ASSET</string-value> </value> </element> <element> <name>ClassId</name> <value> <keyword value-value>Value</keyword-value> </value> </element> <element> <name>Source.ClassId</name> <value> <enum-value>Enum value</enum-value> </value> </element> . . . </instance-attributes>
244
</element> </value> </instance-info> <status> <value/> </status>
245
Update Instance process for v2.0

The Update Instance process updates instances within BMC Atrium CMDB of entity type Class Instance. The following table describes the process inputs for the Update Instance process. Process inputs - Update Instance Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the attribute to update for a specified record in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Update Instance process. <items> XML sample for the Update Instance process
246
<items> <item> <parameters> <username>SOAP user name</username> <password>SOAP password</password> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <items> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </items> <items> <name>Availability</name> <value> <enum-value>High</enum-value> </value> </items> <items> <name>LastScanDate</name> <value> <time-value>03/02/2007 01:00:00 PM</time-value> </value> </items> </attributes> <instance-id>OI-7E0E3E02372A4D3E89B0A403D4239285</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
The following figure illustrates the adapter response for the Update Instance process. Adapter response for the Update Instance process
247
<bmc-atrium-cmdb-response> <item> <metadata> <status></status> </metadata> <parameters> <output> <element> <status-type></status-type> <element> </output> </parameters> </item> </bmc-atrium-cmdb-response>
v2.0 - GraphQuery process for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The following process is included in the v2.0 directory: GraphQuery process
Graph Query process for v2.0

The Graph Query process is exposed as a web service allowing queries for CIs (Configuration Items) and Relationships in BMC Atrium CMDB (Configuration Management DataBase). It starts using the specified CI and follows its relationships to other CIs, continuing along the path to the specified level. The Graph Query API handles a wide range of queries using the adjacency list data structure. The adjacency list contains the object query parameter to specify the CI instances and relation query parameter to specify the relationships to search for in CMDB. The Graph Query API has been tested for Class Instance BMC_BusinesssService and Relationship Instance BMC_BaseRelationship.
The following table describes the process inputs for the Graph Query process. Process Inputs - Graph Query process Process input login info start classname ID start extension ID Description Specifies the authentication parameters Specifies the initial CI namespace and class name Required? Yes Yes
Specifies the starting extension ID of the CI instance This element is used if there is more than one instance of the CI. Use one to indicate the first CI instance.
No
248
start instance ID num levels
Specifies the instance ID of the CI on CMDB Specifies the search direction Valid values: RELATIONSHIP_ DIRECTION_OUT RELATIONSHIP_ DIRECTION_IN
No No
direction
Specifies the search direction Possible values are: RELATIONSHIP_ DIRECTION_OUT RELATIONSHIP_ DIRECTION_IN
No
no match proceed on match proceed graph a get mask
Indicates whether to proceed to the next node if the returned node does not satisfy the query criteria Note: If this element is set to true, no relationship information is displayed. Indicates whether to proceed to the next node if the returned node satisfies the query criteria Specifies the details of the information to be queried on the CMDB to get the CIs and relationships Specifies the dataset type possible values are: GET_MASK_NONE - based on the dataset ID: Searches for the CI and relationships either from overlay or the original dataset. DATASET_MODE_CURRENT: Searches the components in the current dataset only.
No
No No No
a dataset ID
Specifies the unique dataset ID
No
The following figure shows a sample <items> XML for the Graph Query process. <items> XML sample for the Graph Query process
249
<items> <item> <parameters> <login-info> <user-id>Demo</user-id> <password>Demo</password> <lang>English</lang> </login-info> <start-class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </start-class-name-id> <start-extension-id>one</start-extension-id> <start-instance-id>AG0019D12F7F8A1RpqSAj98EAAdSoA</start-instance-id> <num-levels>-1</num-levels> <direction>RELATIONSHIP_DIRECTION_OUT</direction> <no-match-proceed>true</no-match-proceed> <on-match-proceed>true</on-match-proceed> <graph> <items> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </class-name-id> <extension-id>one</extension-id> <adjacency-list> <items> <extension-id>one</extension-id> <object-class-name> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </object-class-name> <object-attribute-names/> <object-attribute-type>ALL</object-attribute-type> <object-query/> <relation-class-name> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BaseRelationship</class-name> </relation-class-name> <relation-attribute-names/> <relation-attribute-type>ALL</relation-attribute-type> <relation-query/> </items> </adjacency-list> </items> </graph> <a-get-mask>GET_MASK_NONE</a-get-mask> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </item> </items>
250
The following figure illustrates the adapter response for the Graph Query process. Adapter response for the Graph Query process
<bmc-atrium-cmdb-response> <metadata> <status>success</status> </metadata> <parameters> <objects> <value> <element> <instance-id>AG0019D12F7F8A8RpqSAl0sFAAgCoA</instance-id> <instance-attributes /> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </class-name-id> </element> <element> <instance-id>AG0019D12F7F8AowBrSAGWFbAwy4IA</instance-id> <instance-attributes /> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </class-name-id> </element> <element> <instance-id>AG0019D12F7F8AiR5rSAuy3QAwVpIA</instance-id> <instance-attributes /> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_BusinessService</class-name> </class-name-id> </element> </value> </objects> <relations /> <status> <value /> </status> </parameters> </bmc-atrium-cmdb-response>
v7.5 - ConfigurationItem processes for BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB
The BMC Atrium Orchestrator application adapter for BMC Atrium CMDB is compatible with BMC Atrium CMDB versions 2.0, 7.5, and 7.6. The processes included in version 7.5 are as follows: [Create CI Instance process] [Delete Instance By Instance Name process]
251
[Delete Instance by InstanceId process] [Delete Instance By Reconciliation Identity process] [Find Instance process] [Update Instance process]
Create CI Instance process for v7.5

The Create CI Instance process creates a Configuration Item within BMC Atrium CMDB for the specified class. The following table describes the process input elements for the Create CI process. Note The CMDB application adapter for the 7.6 release does not contain the Create Relation Instance wrapper. You have use the Create CI Instance wrapper for creating relationship instance. The mandatory attributes need to be specified in the attribute list in order to create a relationship instance. Process Inputs - Create CI Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the attribute for an instance to be created in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Create CI Instance process. <items> XML sample for the Create CI Instance process
<items> <item> <parameters> <username>Demo</username> <password> </password> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <dataset-id>BMC.ASSET</dataset-id> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <list> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </list>
252
<list> <name>AttributeDataSourceList</name> <value> <string-value>attrdataSourceList</string-value> </value> </list> <list> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </list> <list> <name>ShortDescription</name> <value> <string-value>This is test description.</string-value> </value> </list> <list> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </list> <list> <name>Notes</name> <value> <diary-value> <diary-value-in>Test diary field.</diary-value-in> </diary-value> </value> </list> </attributes> </instance-info>
253
The following figure illustrates the adapter response for the Create CI Instance process. Adapter response for the Create CI instance process
<bmc-atrium-cmdb-response> <item> <metadata> <status>Success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> <status> <value/> </status> </parameters> </item> </bmc-atrium-cmdb-response>
Delete Instance By Instance Name process for v7.5

The Delete Instance By Instance Name process deletes a CI or Relationship instances using an instance name within BMC Atrium CMDB. The following table describes the process input elements for the Delete Instance By Instance Name process. Process Inputs - Delete Instance By Instance Name Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Delete Instance By Instance Name process. <items> XML sample for the Delete Instance By Instance Name process
254
<items> <delete-criteria>InstanceName</delete-criteria> <item> <parameters> <username>Demo</username> <password> </password> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-name>Test_Instance_Name</instance-name> <dataset-id>BMC.ASSET</dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By Instance Name process. Adapter response for the Delete Instance By Instance Name
Delete Instance By InstanceId process for v7.5

The Delete Instance by InstanceId process deletes a CI or Relationship instance using an instance ID within BMC Atrium CMDB. The following table describes the process input elements for the Delete Instance by InstanceId process. Process inputs - Delete Instance By InstanceId process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB Required? No Yes
The following figure shows a sample <items> XML for the Delete Instance By InstanceId process.
255
<items> XML sample for the Delete Instance By InstanceId process

<items> <delete-criteria>InstanceId</delete-criteria> <item> <parameters> <username>Demo</username> <password> </password> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> </instance-info> <delete-option>UNCONDITIONALLY</delete-option> <dataset-id>BMC.ASSET</dataset-id> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By InstanceId process. Adapter response for the Delete Instance By InstanceId process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
Delete Instance By Reconciliation Identity process for v7.5

The Delete Instance By Reconciliation Identity process deletes a CI or Relationship instance using a reconciliation identity within BMC Atrium CMDB. The following table describes the process inputs for the Delete Instance By Reconciliation Identity process. Process inputs - Delete Instance By Reconciliation Identity process
256
Process input adapter name items
Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information used to delete a specific instance in BMC Atrium CMDB
Required? No Yes
The following figure shows a sample <items> XML for the Delete Instance By Reconciliation Identity process. <items> XML sample for the Delete Instance By Reconciliation Identity process
<items> <delete-criteria>ReconciliationIdentity</delete-criteria> <item> <parameters> <username>Demo</username> <password> </password> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <reconciliation-identity>RE005056BA243Cq2SKSguroHBQzuMA </reconciliation-identity> <dataset-id>BMC.ASSET</dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </item> </items>
The following figure illustrates the adapter response for the Delete Instance By Reconciliation Identity process. Adapter response for the Delete Instance By Reconciliation Identity process
<bmc-atrium-cmdb-response> <item> <instance-id>InsatanceId9610</instance-id> <metadata> <status>success or error</status> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
Find Instance process for v7.5

The Find Instance process retrieves CI and relationship instances from BMC Atrium CMDB. The following table describes the process input elements for the Find Instance process.
257
Process Inputs - Find Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the information to retrieve records from BMC Atrium CMDB for a specified query Required? No Yes
The following figure shows a sample <items> XML for the Find Instance with selected attributes process. <items> XML for the Find Instance with selected attributes process
<items> <item> <parameters> <username>Demo</username> <password> </password> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <query><![CDATA[AccountID == NULL ]]></query> <attributes> <list>SerialNumber</list> <list>AttributeDataSourceList</list> <list>ClassId</list> <list>ShortDescription</list> <list>Notes</list> <list>OwnerName</list> <list>Name</list> <list>AssignedTo</list> </attributes> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <list> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </list> </sort-order> <dataset-id /> <get-mask>GET_MASK_NONE</get-mask> </parameters> </item> </items>
258
The following figure illustrates the adapter response for the Find Instance process. Adapter response for the Find Instance process
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> <item-count>2</item-count> </metadata> <parameters> <instance-info> <value> <element> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-EECF255CC4664E498A2A41B7A106CA02</instance-id> <instance-attributes> <element> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </element> <element> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </element> <element> <name>AssignedTo</name> <value /> </element> <element> <name>ShortDescription</name> <value> <string-value>This is the 18th CI.</string-value> </value> </element> <element> <name>AttributeDataSourceList</name> <value> <string-value>attrdataSourceList</string-value> </value> </element> <element> <name>Notes</name> <value> <diary-value> <diary-value-out>
259
<element> <user>Demo</user> <text>These are the notes for 18th CI.</text> <timestamp>1247665227000</timestamp> </element> </diary-value-out> </diary-value> </value> </element> <element> <name>OwnerName</name> <value /> </element> <element>
<name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </element> </instance-attributes> </element> <element> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> <instance-attributes> <element> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </element> <element> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </element> <element> <name>AssignedTo</name> <value /> </element> <element> <name>ShortDescription</name> <value> <string-value>This is test description.</string-value> </value> </element> <element> <name>AttributeDataSourceList</name> <value>
260
<string-value>attrdataSourceList</string-value> </value> </element> <element> <name>Notes</name> <value> <diary-value> <diary-value-out> <element> <user>Demo</user> <text>Test diary field.</text> <timestamp>1247674486000</timestamp> </element> </diary-value-out> </diary-value> </value> </element> <element> <name>OwnerName</name> <value /> </element> <element> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </element> </instance-attributes> </element> </value> </instance-info> <status> <value /> </status>
261
Update Instance process for v7.5

The Update Instance process updates instances within BMC Atrium CMDB of entity type Class Instance. The following table describes the process inputs for the Update Instance process. Process inputs - Update Instance process Process input adapter name items Description Specifies the name of the adapter to use to handle the request Default value: BMCAtriumCMDBActorAdapter Specifies an XML document containing the attribute to update for a specified record in BMC Atrium CMDB. Required? No Yes
The following figure shows a sample <items> XML for the Update Instance process. <items> XML sample for the Update Instance process
262
<items> <item> <parameters> <username>Demo</username> <password> </password> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <items> <name>ShortDescription</name> <value> <string-value>This is the updated description.</string-value> </value> </items> <items> <name>SerialNumber</name> <value> <string-value>444</string-value> </value> </items> </attributes> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> </instance-info> <dataset-id>BMC.ASSET</dataset-id> </parameters> </item> </items>
The following figure illustrates the adapter response for the Update Instance process. Adapter response for the Update Instance process
<bmc-atrium-cmdb-response> <item> <metadata> <status>Success or error</status> <error>Present only with status of 'error'</error> </metadata> <parameters> <output/> </parameters> </item> </bmc-atrium-cmdb-response>
263
BMC Atrium Orchestrator features for BMC Atrium CMDB Classes with parameter mapping
The BMC Atrium Orchestrator adapter for BMC Atrium CMDB provides a parameter-mapping feature for enum value and time value data types for the following classes:
CI classes with mapped parameters

BMC_Document BMC_Equipment BMC_Person BMC_ProtocolEndpoint BMC_ConnectivityCollection BMC_Organization BMC_Role BMC_UserCommunity BMC_Account BMC_Activity BMC_BusinessService BMC_DataBase BMC_PhysicalLocation BMC_AdminDomain BMC_ApplicationSystem BMC_Cluster BMC_ComputerSystem BMC_HardwareSystemComponent BMC_LogicalSystemComponent BMC_ApplicationService
Relationship classes with mapped parameters

BMC_Component BMC_Dependency BMC_MemberofCollection BMC_ElementLocation With this mapping feature, users provide values as displayed through the user interface (UI) in BMC Atrium CMDB, rather than the actual numeric values held in the database. parameter values are mapped by the adapter as needed, to translate between the UI value and the database value. Users can also interface with classes for which the mapped parameter feature is not available. When executing requests against these classes, the numeric database value must be used. Examples of values to be used with both mapped and unmapped classes are provided for each data type, enum value and time value, in the following sections.
Enum Value parameter mapping

Values with a data type of 'enum value' are displayed as text in the UI but are stored as numeric values in the database. For example, the value on screen can be 'High' or 'Low' while the value in the data record is '10' or '20'. The following samples show how the values would be used for a class with mapped parameters and for a class for which the mapped parameters feature is not available. The following figure shows the value for Confidentiality field for class with parameter mapping.
264
Value for Confidentiality field for class with parameter mapping

<element> <name>Confidentiality</name> <value> <enum-value>High</enum-value> </value> </element>
The following figure shows the value for Confidentiality field for class without parameter mapping Value for Confidentiality field for class without parameter mapping
<element> <name>Confidentiality</name> <value> <enum-value>10</enum-value> </value> </element>
Time Value parameter mapping

Values with a data type of time value are displayed in a standard date/time format in the UI but are stored as numeric values, in epoch time format, in the database. For example, the value on screen can be '03/30/2007 02:58:46 PM' while the value in the data record is '1175246926000'. The following samples show how the values would be used for a class with mapped parameters and for a class for which the mapped parameters feature is not available. The following figure shows the value for Create Date field for class with parameter mapping. Value for Create Date field for class with parameter mapping
<element> <name>CreateDate</name> <value> <time-value>03/30/2007 02:58:46 PM</time-value> </value> </element>
The following figure shows the value for Create Date field for class without parameter mapping. Value for Create Date field for class without parameter mapping
<element> <name>CreateDate</name> <value> <time-value>1175246926000</time-value> </value> </element>
265
BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB requests and responses for v2.0
The adapter performs the following operations in BMC Atrium CMDB 2.0: create-instance create-relation-instance delete-instance get-instances set-instance
Adapter request and response for the create-instance operation for v2.0
The create-instance operation creates a configuration item within BMC Atrium CMDB for the specified class. The following figure shows the XML template of the adapter request for the create-instance operation. XML template of the adapter request for the create-instance operation
266
<bmc-atrium-cmdb-request> <username></username> <password></password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>create-instance</operation-name> <parameters> <login-info> <user-id></user-id> <password></password> <lang></lang> </login-info> <class-name-id> <namespace-name></namespace-name> <class-name></class-name> </class-name-id> <attributes> <items> <name></name> <value> <string-value></string-value> </value> </items> <items> <name></name> <value> <time-value></time-value> </value> </items> </attributes> <a-dataset-id></a-dataset-id> </parameters> </request> </bmc-atrium-cmdb-request>
The following figure shows an XML sample of the adapter request for the create-instance operation. XML sample of the adapter request for the create-instance operation
267
<bmc-atrium-cmdb-request> <username>SOAP user name</username> <password>SOAP password</password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>create-instance</operation-name> <parameters> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <attributes> <items> <name>Attribute name 1</name> <value> <string-value>value for attribute name 1</string-value> </value> </items> <items> <name>Attribute name 2</name> <value> <time-value>12/31/2007 06:00:00 PM</time-value> </value> </items> . . . </attributes> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </request> </bmc-atrium-cmdb-request>
The following table describes the adapter request elements for the create-instance operation. Adapter request elements for the create-instance operation Element username Description Specifies the user name for SOAP authentication Required? No
268
password
Specifies the password that corresponds to the <username> specified
No Yes
generator-version Specifies the version of the BMC Atrium Orchestrator web services WSDL-based client generator Valid value: 1.0 request service namespace name port namespace name operation-name parameters login-info user-id password lang class-name-id Specifies the request elements Specifies the BMC Atrium CMDB service information Specifies the URL for the BMC Atrium CMDB service Valid value: http://cmdb.bmc.com Specifies the name of the BMC Atrium CMDB service Valid value: CMDB_Service Specifies the BMC Atrium CMDB port information. Specifies the URL for the BMC Atrium CMDB port Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB port name Valid value: CMDB_WebService Specifies the operation type Specifies the data types and elements of the operation Specifies the authentication information for BMC Atrium CMDB Specifies the User ID for BMC Atrium CMDB authentication Specifies the password that corresponds with the <user-id> provided Specifies the language used for BMC Atrium CMDB You must at least specify an empty value, <lang/>. Specifies the class information for the request
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
namespace-name Specifies the namespace used to reference the class name id Valid values: BMC.CORE BMC.CORE.CONFIG
269
class-name
Specifies the class name of the CI instances to be created For non-mapped classes the raw data must be provided for attributes with a data type of enum value or time value. The following are the CI Classes with mapped parameters: BMC_Document BMC_Equipment BMC_Person BMC_ProtocolEndpoint BMC_ConnectivityCollection BMC_Organization, BMC_Role BMC_UserCommunity BMC_Account, BMC_Activity BMC_BusinessService BMC_DataBase BMC_PhysicalLocation BMC_AdminDomain BMC_ApplicationSystem BMC_Cluster BMC_ComputerSystem BMC_HardwareSystemComponent BMC_LogicalSystemComponent BMC_ApplicationService
Yes
attributes items name value {data type}-value
Specifies the name/value pairs for the attributes of the created record Specifies the name/value pair Specifies the attribute name Specifies the data-type for the attributes Specifies the value for the specified the attribute The tag should include the data type. Valid values: <int-value> <keyword-value> <long-value> <bit-mask-value> <ulong-value> <double-value> <string-value> <diary-value> <enum-value> <time-value> <time-of-day-value> <byte-list-value> <decimal-value> <attach-value> <coord-list-value> <date-value> <currency-value>
Yes Yes Yes Yes Yes
270
a-dataset-id
Specifies the identifier for the dataset Sample values: BMC.ASSET BMC.SAMPLE
Yes
Note When the adapter request is formed within the Transformer Editor, this template must be enclosed in <request-data> tags. The create-instance operation request returns an adapter response that contains the ID of the newly created instance. The following figure illustrates an XML sample of the adapter response for the create-instance operation. XML sample of the adapter response with create-instance operation
<bmc-atrium-cmdb-response> <item> <metadata> <status>success>/status> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value/> </status> </parameters> </item> </bmc-atrium-cmdb-response>
The following table describes the adapter response elements for the create instance operation. Adapter response elements for the create-instance operation Element item metadata status Description Contains the response information Contains the command summary information Indicates the status of the request Valid values: success, error
parameters Contains the response elements that define the instance created instance-id status value Contains the ID of the created instance Contains the value returned by BMC Atrium CMDB regarding the creation of the instance Contains the error message, if any
271
Adapter request and response for the create-relation-instance operation for v2.0
The create-relation-instance operation request creates a relationship between two or more instances within BMC Atrium CMDB. The following figure shows the XML template of the adapter request for the create-relation-instance operation. XML template of the adapter request for the create-relation-instance operation
272
<bmc-atrium-cmdb-request> <username></username> <password></password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>create-relation-instance</operation-name> <parameters> <login-info> <user-id></user-id> <password></password> <lang></lang> </login-info> <class-type></class-type> <class-name-id> <namespace-name></namespace-name> <class-name></class-name> </class-name-id> <role1Name></role1Name> <instance1Id></instance1Id> <class1Id></class1Id> <role2Name></role2Name> <instance2Id></instance2Id> <class2Id></class2Id> <a-dataset-id></a-dataset-id> <attributes> <items> <name></name> <value> <string-value></string-value> </value> </items> <items> <name></name> <value> <time-value></time-value> </value> </items> </attributes> </parameters> </request> </bmc-atrium-cmdb-request>
The following figure shows an XML sample of the adapter request for the create-relation-instance operation. XML sample of the adapter request for the create-relation-instance operation
273
<bmc-atrium-cmdb-request> <username>SOAP user name</username> <password>SOAP password</password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>create-relation-instance</operation-name> <parameters> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <role1Name>Source</role1Name> <instance1Id>OI-8081A4AF60BD451EAB53C2550246CC4C</instance1Id> <class1Id>BMC_ACCOUNT</class1Id> <role2Name>Destination</role2Name> <instance2Id>OI-153F67CBFDB74210A689949D91F89F96</instance2Id> <class2Id>BMC_ACCOUNT</class2Id> <a-dataset-id>BMC.ASSET</a-dataset-id> <attributes> <items> <name>Attribute name 1</name> <value> <string-value>value for attribute name 1</string-value> </value> </items> <items> <name>Attribute name 2</name> <value> <time-value>12/31/2007 09:00 PM</time-value> </value> </items> . . . </attributes> </parameters> </request> </bmc-atrium-cmdb-request>
The following table describes the adapter request elements for the create-relation -instance operation.
274
Adapter request elements for the create-relation-instance operation Element username password Description Specifies the user name to be used SOAP authentication Specifies the password that corresponds to the <username> specified Required? No No Yes
generator-version Specifies the version of the BMC Atrium Orchestrator web services WSDL-based client generator Valid value: 1.0 request service namespace name port namespace name operation-name parameters login-info user-id password lang class-name-id Specifies the request elements. Specifies the BMC Atrium CMDB service information Specifies the URL for the BMC Atrium CMDB service Valid value: http://cmdb.bmc.com Specifies the name of the BMC Atrium CMDB service name Valid value: CMDB_Service Specifies the BMC Atrium CMDB port information Specifies the URL for the BMC Atrium CMDB port Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB port name Valid value: CMDB_WebService Specifies the type of operation. Specifies the data types and elements of the operation Specifies the authentication information for BMC Atrium CMDB Specifies the User ID to be used for BMC Atrium CMDB authentication Specifies the password that corresponds with the <user-id> provided Specifies the language used for BMC Atrium CMDB At the least, you must specify an empty value, <lang/>. Specifies the class information for the request
namespace-name Specifies the namespace used to reference the class name id Sample values: BMC.CORE BMC.CORE.CONFIG class-name Specifies the class name of the Relationship instances to be created For non-mapped classes, you must provide the raw data for attributes with a data type of enum value or time value. The following are the relationship classes with mapped parameters: BMC_Component BMC_Dependency BMC_MemberofCollection BMC_ElementLocation
Yes
275
role1Name
Specifies the role of the first instance specified Valid values: Source (defines a parent instance) Destination (defines a child instance)
Yes
instance1Id class1Id role2Name
Specifies the instance ID of the first instance Specifies the class ID of the first instance Specifies the role of the second instance specified Valid values: Source (defines a parent instance) Destination (defines a child instance)
Yes Yes Yes
instance2Id class2Id a-dataset-id
Specifies the instance ID of the second instance Specifies the class ID of the second instance Specifies the identifier for the dataset Sample values: BMC.ASSET BMC.SAMPLE
Yes Yes Yes
attributes items name value {data type}-value
Specifies the name and value pairs for the attributes of the created record Specifies the name and value pair Specifies the attribute name Specifies the data-type for the attributes Specifies the value for the specified attribute The tag should include the data type. Valid values: <int-value> <keyword-value> <long-value> <bit-mask-value> <ulong-value> <double-value> <string-value> <diary-value> <enum-value> <time-value> <time-of-day-value> <byte-list-value> <decimal-value> <attach-value> <coord-list-value> <date-value> <currency-value>
Yes Yes Yes Yes Yes
276
Note When the adapter request is formed within the Transformer Editor, this template must be enclosed in <request-data> tags. The create-relation-instance operation request returns an adapter response that contains the ID of the newly created relationship instance. The following figure illustrates an XML sample of the adapter response for the create-relation-instance operation. XML sample of the adapter response for the create-relation-instance operation
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> </metadata> <parameters> <instance-id>OI-AA1663B72DCF47E4B48B7B83699C3D37</instance-id> <status> <value/> </status> </parameters> </bmc-atrium-cmdb-response>
The following table describes the adapter response elements for the create-relation-instance operation. Adapter response elements for the create-relation-instance operation Element item metadata status Description Contains the response information Contains the command summary information Contains the status of the request Valid values: success, error
parameters Contains the response elements that define the instance created instance-id status value Contains the ID of the created instance Contains the value returned by BMC Atrium CMDB regarding the creation of the instance Contains the error message, if any
Adapter request and response for the delete-instance operation for v2.0
The delete-instance operation deletes a configuration item or a relationship within BMC Atrium CMDB. The following figure shows an the XML template of the adapter request for the delete-instance operation. XML template of the adapter request for the delete-instance operation
277
<bmc-atrium-cmdb-request> <username></username> <password></password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>delete-instance</operation-name> <parameters> <login-info> <user-id></user-id> <password></password> <lang></lang> </login-info> <class-name-id> <namespace-name></namespace-name> <class-name></class-name> </class-name-id> <instance-id></instance-id> <a-dataset-id></a-dataset-id> <delete-option></delete-option> </parameters> </request> </bmc-atrium-cmdb-request>
The following figure shows an XML sample of the adapter request for the delete-instance operation. XML sample of the adapter request for the delete-instance operation
278
<bmc-atrium-cmdb-request> <username>SOAP user name</username> <password>SOAP password</password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>delete-instance</operation-name> <parameters> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password> BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <instance-id>OI-C5E85EDDDA3C486790756FC07C61394D</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </request> </bmc-atrium-cmdb-request>
The following table describes the adapter request elements for the delete-instance operation. Adapter request elements for the delete-instance operation Element username password Description Specifies the user name to be used for SOAP authentication Specifies the password that corresponds to the <username> specified Required? No No Yes
generator-version Specifies the version of the BMC Atrium Orchestrator web services WSDL-based client generator Valid value: 1.0 request service namespace name port Specifies the request elements Specifies the BMC Atrium CMDB service information Specifies the URL for the BMC Atrium CMDB service Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB service name Valid value: CMDB_Service Specifies the BMC Atrium CMDB port information
Yes Yes Yes Yes Yes
279
namespace name operation-name parameters login-info user-id password lang class-name-id
Specifies the URL for the BMC Atrium CMDB port Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB port name Valid value: CMDB_WebService Specifies the type of operation Specifies the data types and elements of the operation Specifies the authentication information for CMDB Specifies the User ID to be used for BMC Atrium CMDB authentication Specifies the password that corresponds with the <user-id> provided Specifies the language used for BMC Atrium CMDB At the least, you must specify an empty value, <lang/>. Specifies the class information for the request
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
namespace-name Specifies the namespace used to reference the class name id Examples: BMC.CORE BMC.CORE.CONFIG class-name Specifies the class name of the CI and Relationship instances to be deleted For non-mapped classes, you must provide the raw data for attributes with a data type of enum value or time value. CI classes with mapped parameters: BMC_Document BMC_Equipment BMC_Person BMC_ProtocolEndpoint BMC_ConnectivityCollection BMC_Organization BMC_Role BMC_UserCommunity BMC_Account BMC_Activity BMC_BusinessService BMC_DataBase BMC_PhysicalLocation BMC_AdminDomain BMC_ApplicationSystem BMC_Cluster BMC_ComputerSystem BMC_HardwareSystemComponent BMC_LogicalSystemComponent BMC_ApplicationService Relationship classes with mapped parameters: BMC_Component BMC_Dependency BMC_MemberofCollection BMC_ElementLocation instance-id Specifies the unique identifier for the instance to be deleted
Yes
Yes
280
a-dataset-id
Specifies the identifier for the dataset Sample values: BMC.ASSET BMC.SAMPLE
Yes
delete-option
Specifies the type of delete operation Valid values: UNCONDITIONALLY (Deletes the instance even when the instance cannot be retrieved) DERIVED_INSTANCE_FOUND (Deletes only the specified instance, if the instance is retrieved).
Yes
Note When the adapter request is formed within the Transformer Editor, this template must be enclosed in <request-data> tags. The delete operation request returns an adapter response that contains results of the operation. The following figure illustrates an XML sample of the adapter response for the delete-instance operation. XML sample of the adapter response for the delete-instance operation
bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> </metadata> <parameters> <output/> </parameters> </bmc-atrium-cmdb-response>
The following table describes the adapter response elements for the delete instance Adapter response elements for the delete-instance operation Element item metadata status Description Contains the response information Contains the command summary information Contains the status of the request Valid values: success, error
parameters Contains the parameters returned by the CMDB application for delete-instance operation
Adapter request and response for the get-instances operation for v2.0
281
The get-instances operation retrieves configuration item records within BMC Atrium CMDB. The following figure shows an XML template of the adapter request for the get-instances operation. XML template of the adapter request for the get-instances operation
<bmc-atrium-cmdb-request> <username></username> <password></password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>get-instances</operation-name> <parameters> <login-info> <user-id></user-id> <password></password> <lang></lang> </login-info> <class-name-id> <namespace-name></namespace-name> <class-name></class-name> </class-name-id> <query></query> <attributes/> <first-retrieve></first-retrieve> <max-retrieve></max-retrieve> <sort-order> <items> <attribute-name></attribute-name> <sort-order></sort-order> </items> </sort-order> <a-dataset-id/> <a-get-mask></a-get-mask> </parameters> </request> </bmc-atrium-cmdb-request>
The following figure shows an XML sample of the adapter request for the get-instances operation. XML sample of the adapter request for the get-instances operation
282
<bmc-atrium-cmdb-request> <username>SOAP user name</username> <password>SOAP password</password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>get-instances</operation-name> <parameters> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <query><![CDATA[AccountID != NULL]]></query> <attributes/> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <items> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </items> </sort-order> <a-dataset-id/> <a-get-mask>GET_MASK_NONE</a-get-mask> </parameters> </request> </bmc-atrium-cmdb-request>
The following table describes the adapter request elements for the get-instances operation. Adapter request elements for the get-instances operation Element username password Description Specifies the user name for SOAP authentication Specifies the password that corresponds to the <username> specified Required No No Yes
generator-version Specifies the version of the BMC Atrium Orchestrator web services WSDL-based client generator Valid value: 1.0 request Specifies the request elements
Yes
283
service namespace name port namespace name operation-name parameters login-info user-id password lang class-name-id
Specifies the BMC Atrium CMDB service information Specifies the URL for the BMC Atrium CMDB service Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB service name Valid value: CMDB_Service Specifies the BMC Atrium CMDB port information Specifies the URL for the BMC Atrium CMDB port Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB port name Valid value: CMDB_WebService Specifies the type of operation Specifies the data types and elements of the operation Specifies the authentication information for BMC Atrium CMDB Specifies the User ID to be used for BMC Atrium CMDB authentication Specifies the password that corresponds with the <user-id> Specifies the language used for BMC Atrium CMDB At the least, you must specify an empty value <lang/>. Specifies the class information for the request
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
namespace-name Specifies the namespace used to reference the class name id Sample values: BMC.CORE BMC.CORE.CONFIG
284
class-name
Specifies the class name of CI and relationship instances You must provide raw data for non-mapped parameters*.* For non-mapped classes, you must provide the raw data for attributes with a data type of enum value or time value. The following are the CI classes with mapped parameters: BMC_Document BMC_Equipment, BMC_Person BMC_ProtocolEndpoint BMC_ConnectivityCollection BMC_Organization BMC_Role BMC_UserCommunity BMC_Account BMC_Activity BMC_BusinessService BMC_DataBase BMC_PhysicalLocation BMC_AdminDomain BMC_ApplicationSystem BMC_Cluster BMC_ComputerSystem BMC_HardwareSystemComponent BMC_LogicalSystemComponent BMC_ApplicationService Relationship classes with mapped parameters: BMC_Component BMC_Dependency BMC_MemberofCollection BMC_ElementLocation
Yes
query
Specifies the qualification that determines the set of instances to retrieve The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic operations. The criteria must be specified as CDATA. Specifies the list of attribute names to retrieve To retrieve all the attributes for the matching instances, leave this element blank. Specifies the first instance to retrieve Valid value: integer Specifies the maximum number of records to retrieve Valid value: integer Specify 0 to retrieve all data. Specifies the sorting criteria Specifies the attribute and sort order values Specifies the name of the attribute on which to sort Specifies the sort order for the retrieved data Valid values: ASCENDING DESCENDING
Yes
attributes first-retrieve max-retrieve
Yes Yes Yes
sort-order items attribute-name sort-order
Yes Yes Yes Yes
285
a-dataset-id
Specifies the identifier for the dataset At minimum an empty value must be supplied For example, <a-dataset-id/>). Valid values: BMC.ASSET BMC.SAMPLE
Yes
a-get-mask
Specifies the identifier for specifying the dataset type. Valid values: GET_MASK_NONE (Based on the datasetId being passed, instances are retrieved from either the overlay or the original dataset.) DATASET_MODE_CURRENT (Retrieve instances from the current dataset only).
Yes
Note When the adapter request is formed within the Transformer Editor, this template must be enclosed in <request-data> tags. The get-instances operation request returns an adapter response that contains the records that match the query criteria in the adapter request. The following figure shows an XML sample of the adapter response for the get-instances operation. XML sample of the adapter response for the get-instances operation
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> <item-count>2</item-count> </metadata> <parameters> <instance-info> <value> <element> <instance-id>AG4445535442002zkKRgKhCFHglU0B</instance-id> <instance-attributes> <element> <name>Destination.ReconciliationIdentity</name> <value> <string-value>P3</string-value> </value> </element> <element> <name>Destination.DatasetId</name> <value> <string-value>BMC.ASSET</string-value> </value> </element> <element> <name>ClassId</name> <value>
286
<keyword value-value>Value</keyword-value> </value> </element> <element> <name>Source.ClassId</name> <value> <enum-value>Enum value</enum-value> </value> </element> . . . </instance-attributes> </element> <element> <instance-id>AG4445535442002zkKRgI2GGHgz00B</instance-id> <instance-attributes> <element> <name>Destination.ReconciliationIdentity</name> <value> <string-value>P3</string-value> </value> </element> <element> <name>Destination.DatasetId</name> <value> <string-value>BMC.ASSET</string-value> </value> </element> <element> <name>ClassId</name> <value> <keyword value-value>Value</keyword-value> </value> </element> <element> <name>Source.ClassId</name> <value> <enum-value>Enum value</enum-value> </value> </element> . . . </instance-attributes> </element> </value> </instance-info> <status> <value/> </status>
287
The following table describes the adapter response elements for the get-instances operation. Adapter response elements for the get-instances operation Data Element item metadata status parameters instance-info value element instance-id Description Contains the response information Contains the command summary information Contains the status of the request Valid values: success, error. Contains the response data that defines the get-instances created Contains the information on the instance retrieved Contains the information for all matching entries Contains the details of each retrieved instance Contains the unique identifier for the instance
instance-attributes Contains the list of attributes values for the instance response element name value {data-type}-value Contains the element retrieved for the particular instance Contains the attribute name Contains the attribute value Contains the value for the specified attribute The tag includes the data type. Valid values: <int-value> <keyword-value> <long-value> <bit-mask-value> <ulong-value> <double-value> <string-value> <diary-value> <enum-value> <time-value> <time-of-day-value> <byte-list-value> <decimal-value> <attach-value> <coord-list-value> <date-value> <currency-value> status Contains the search operation as returned by CMDB application
288
value
Contains the error message, if any
Adapter request and response for the set-instance operation for v2.0
The set-instance operation updates specified values for a configuration item within BMC Atrium CMDB. The following figure shows an XML template of the adapter request for the set-instance operation. XML template of the adapter request for the set-instance operation
289
<bmc-atrium-cmdb-request> <username></username> <password></password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>set-instance</operation-name> <parameters> <login-info> <user-id></user-id> <password></password> <lang></lang> </login-info> <class-name-id> <namespace-name></namespace-name> <class-name></class-name> </class-name-id> <attributes> <items> <name></name> <value> <string-value></string-value> </value> </items> <items> <name></name> <value> <time-value></time-value> </value> </items> </attributes> <instance-id></instance-id> <a-dataset-id></a-dataset-id> </parameters> </request> </bmc-atrium-cmdb-request>
The following figure shows an XML sample of the adapter request for the set-instance operation. XML sample of the adapter request for the set-instance operation
290
<bmc-atrium-cmdb-request> <username>SOAP user name</username> <password>SOAP password</password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_Service</name> </service> <port> <namespace>http://cmdb.bmc.com</namespace> <name>CMDB_WebService</name> </port> <operation-name>set-instance</operation-name> <parameters> <login-info> <user-id>BMC Atrium CMDB user ID</user-id> <password>BMC Atrium CMDB password</password> <lang>English</lang> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Person</class-name> </class-name-id> <attributes> <items> <name>Attribute name 1</name> <value> <string-value>New Value for Attribute name 1</string-value> </value> </items> <items> <name>Attribute name 2</name> <value> <time-value>12/31/2007 09:00:00 AM</time-value> </value> </items> . . . </attributes> <instance-id>OI-C5E85EDDDA3C486790756FC07C61394D</instance-id> <a-dataset-id>BMC.ASSET</a-dataset-id> </parameters> </request> </bmc-atrium-cmdb-request>
The following table describes the adapter request elements for the set-instance operation. Adapter request elements for the set-instance operation Element Description Required
291
username password
Specifies the user name for SOAP authentication Specifies the password that corresponds to the <username> specified
No No Yes
generator-version Specifies the version of the BMC Atrium Orchestrator web services WSDL based client generator Valid value: 1.0 request service namespace name port namespace name operation-name parameters login-info user-id password lang class-name-id Specifies the request elements Specifies the BMC Atrium CMDB service information Specifies the URL for the BMC Atrium CMDB service Valid value: http://cmdb.bmc.com Specifies the name of the BMC Atrium CMDB service Valid value: CMDB_Service Specifies the BMC Atrium CMDB port information Specifies the URL for the BMC Atrium CMDB port Valid value: http://cmdb.bmc.com Specifies the BMC Atrium CMDB port name Valid value: CMDB_WebService Specifies the type of operation Specifies the elements that define the create-instance Specifies the authentication information for BMC Atrium CMDB Specifies the User ID for BMC Atrium CMDB authentication Specifies the password that corresponds to the <user-id> provided Specifies the language used for BMC Atrium CMDB At the least, you must specify an empty value, <lang/>. Specifies the class information for the request
namespace-name Specifies the namespace used to reference the class name id Sample values: BMC.CORE BMC.CORE.CONFIG
292
class-name
Specifies the class name of the CI or relationship instance to be updated For non-mapped classes, you must provide the raw data for attributes with a data type of enum value or time value. The following are the CI classes with mapped parameters: BMC_Document BMC_Equipment BMC_Person BMC_ProtocolEndpoint BMC_ConnectivityCollection BMC_Organization BMC_Role BMC_UserCommunity BMC_Account BMC_Activity BMC_BusinessService BMC_DataBase BMC_PhysicalLocation BMC_AdminDomain BMC_ApplicationSystem BMC_Cluster BMC_ComputerSystem BMC_HardwareSystemComponent BMC_LogicalSystemComponent BMC_ApplicationService Relationship classes with mapped parameters: BMC_Component BMC_Dependency BMC_MemberofCollection BMC_ElementLocation
No
attributes items name value
Specifies the name and value pairs for the attributes to be updated Specifies the name and value pair Specifies the attribute name Specifies the data-type for the attributes
No Yes Yes Yes
293
{data type}-value
Specifies the value for the specified the attribute The tag includes the data type. Valid values: <int-value> <keyword-value> <long-value> <bit-mask-value> <ulong-value> <double-value> <string-value> <diary-value> <enum-value> <time-value> <time-of-day-value> <byte-list-value> <decimal-value> <attach-value> <coord-list-value> <date-value> <currency-value>
Yes
instance-id a-dataset-id
Specifies the unique identifier for the instance Specifies the identifier for the dataset Sample values: BMC.ASSET BMC.SAMPLE
Yes Yes
Note When the adapter request is formed within the Transformer Editor, this template must be enclosed in <request-data> tags. The set-instance operation request returns an adapter response that contains the status of the instance update process. The following figure illustrates an XML sample of the adapter response for the set-instance operation. XML sample of the adapter response for the set-instance operation
294
<bmc-atrium-cmdb-response> <item> <metadata> <status></status> </metadata> <parameters> <output> <element> <status-type></status-type> <element> </output> </parameters> </item> </bmc-atrium-cmdb-response>
The following table describes the adapter response elements for the set-instance operation. Adapter response elements for set-instance operation Data Element item metadata status parameters element status-type Description Contains the response information Contains the command summary information Contains the status of the request Valid values: success, error. Contains the parameters returned by BMC Atrium CMDB application to indicate status of instance update process Contains the response status and message text Contains the status of the command execution
message-text Contains the message returned upon an error output Contains the output element containing the errors returned
BMC Atrium Orchestrator Application Adapter for BMC Atrium CMDB requests and responses for v7.5 and v7.6
Following are the operations that the adapter performs in the 7.5 and 7.6 releases: create-instance delete-instance get-instances set-instance The following table describes the elements for the adapter requests. Adapter request elements for 7.5 and 7.6 requests
295
Element username password locale time-zone
Description Specifies the user name for the BMC Atrium CMDB authentication Specifies the password that corresponds to the specified <username> Specifies the locale used for BMC Atrium CMDB Specifies the time zone for BMC Atrium CMDB
authentication Specifies the authentication string provided by the adapter, for example, domain
Adapter request and response for the create-instance operation for v7.5 and 7.6
The create-instance operation creates a configuration item within BMC Atrium CMDB for the specified class. The following figure describes the adapter request for the create-instance operation. XML sample of the adapter request for the create-instance operation
<bmc-atrium-cmdb-request> <username>Demo</username> <password> </password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>atrium_instances</name> </service> <port> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>AtriumInstances_PortType_EP</name> </port> <operation-name>create-instance</operation-name> <parameters> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <dataset-id>BMC.ASSET</dataset-id> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <list> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </list> <list>
296
<name>AttributeDataSourceList</name> <value> <string-value>attrdataSourceList</string-value> </value> </list> <list> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </list> <list> <name>ShortDescription</name> <value> <string-value>This is test description.</string-value> </value> </list> <list> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </list> <list> <name>Notes</name> <value> <diary-value> <diary-value-in>Test diary field.</diary-value-in> </diary-value> </value> </list> </attributes> </instance-info>
297
</parameters> </request> </bmc-atrium-cmdb-request>
See Adapter request and response for the create-instance operation for v2.0 for the description of the adapter request and response elements. The following figure illustrates the XML sample of the adapter response for the create-instance operation. XML sample of the adapter response for the create-instance operation
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> </metadata> <parameters> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> <status> <value /> </status> </parameters> </item> </bmc-atrium-cmdb-response>
Adapter request and response for the delete-instance operation for v7.5 and 7.6
The delete-instance operation deletes a configuration item or a relationship within BMC Atrium CMDB. The following figure describes the adapter request for the delete-instance operation. XML sample of the adapter request for the delete-instance operation
298
<bmc-atrium-cmdb-request> <username>Demo</username> <password> </password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>atrium_instances</name> </service> <port> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>AtriumInstances_PortType_EP</name> </port> <operation-name>delete-instance</operation-name> <parameters>
<login-info> <locale /> <time-zone /> <authentication /> </login-info> <dataset-id>BMC.ASSET</dataset-id> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> </instance-info> <delete-option>UNCONDITIONALLY</delete-option> </parameters> </request> </bmc-atrium-cmdb-request>
See Adapter request and response for the delete-instance operation for v2.0 for the description of the adapter request and response elements. The following figure illustrates the adapter response for the delete-instance operation. XML sample of the adapter response for the delete-instance operation
299
Adapter request and response for the get-instances operation for v7.5 and 7.6
The get-instances operation retrieves configuration item records within BMC Atrium CMDB. The following figure describes the adapter request for the get-instances operation. XML sample of the adapter request for the get-instances operation
300
<bmc-atrium-cmdb-request> <username>Demo</username> <password> </password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>atrium_instances</name> </service> <port> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>AtriumInstances_PortType_EP</name> </port> <operation-name>get-instances</operation-name> <parameters> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <list>SerialNumber</list> <list>AttributeDataSourceList</list> <list>ClassId</list> <list>ShortDescription</list> <list>Notes</list> <list>OwnerName</list> <list>Name</list> <list>AssignedTo</list> </attributes> <query>AccountID == NULL </query> <first-retrieve>0</first-retrieve> <max-retrieve>10</max-retrieve> <sort-order> <list> <attribute-name>SerialNumber</attribute-name> <sort-order>ASCENDING</sort-order> </list> </sort-order> <dataset-id /> <get-mask>GET_MASK_NONE</get-mask> </parameters> </request> </bmc-atrium-cmdb-request>
See Adapter request and response for the get-instances operation for v2.0 for the description of the adapter request and response elements. The following figure illustrates the XML sample of the adapter response for the get-instances operation.
301
XML sample of the adapter response for the get-instances operation
<bmc-atrium-cmdb-response> <item> <metadata> <status>success</status> <item-count>2</item-count> </metadata> <parameters> <extensions/> <instance-info> <value> <element> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-EECF255CC4664E498A2A41B7A106CA02</instance-id> <instance-attributes> <element> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </element> <element> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </element> <element> <name>AssignedTo</name> <value/> </element> <element> <name>ShortDescription</name> <value> <string-value>This is the 18th CI.</string-value> </value> </element> <element> <name>AttributeDataSourceList</name> <value> <string-value>attrdataSourceList</string-value> </value> </element> <element> <name>Notes</name> <value> <diary-value> <diary-value-out> <element> <user>Demo</user>
302
<text>These are the notes for 18th CI.</text> <timestamp>1247665227000</timestamp> </element> </diary-value-out> </diary-value> </value> </element> <element> <name>OwnerName</name> <value/> </element> <element> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </element> </instance-attributes> </element> <element> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> <instance-attributes> <element> <name>SerialNumber</name> <value> <string-value>999</string-value> </value> </element> <element> <name>ClassId</name> <value> <string-value>BMC_ACCOUNT</string-value> </value> </element> <element> <name>AssignedTo</name> <value/> </element> <element> <name>ShortDescription</name> <value> <string-value>This is test description.</string-value> </value> </element> <element> <name>AttributeDataSourceList</name> <value> <string-value>attrdataSourceList</string-value> </value> </element> <element> <name>Notes</name>
303
<value> <diary-value> <diary-value-out> <element> <user>Demo</user> <text>Test diary field.</text> <timestamp>1247674486000</timestamp> </element> </diary-value-out> </diary-value> </value> </element> <element> <name>OwnerName</name> <value/> </element> <element> <name>Name</name> <value> <string-value>TestClassInstance</string-value> </value> </element> </instance-attributes> </element> </value> </instance-info> <status> <value/> </status>
304
Adapter request and response for the set-instance operation for v7.5 and 7.6
The set-instance operation updates specified values for a configuration item within BMC Atrium CMDB. The following figure describes the adapter request for the set-instance operation. XML sample of the adapter request for the set-instance operation
305
<bmc-atrium-cmdb-request> <username>Demo</username> <password> </password> <generator-version>1.0</generator-version> <request> <service> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>atrium_instances</name> </service> <port> <namespace>http://atrium.bmc.com/2009/01/instances</namespace> <name>AtriumInstances_PortType_EP</name> </port> <operation-name>set-instance</operation-name> <parameters> <login-info> <locale /> <time-zone /> <authentication /> </login-info> <instance-info> <class-name-id> <namespace-name>BMC.CORE</namespace-name> <class-name>BMC_Account</class-name> </class-name-id> <attributes> <items> <name>ShortDescription</name> <value> <string-value>This is the updated description.</string-value> </value> </items> <items> <name>SerialNumber</name> <value> <string-value>444</string-value> </value> </items> </attributes> <instance-id>OI-D1D36E01259748B3A8D9A02914C22049</instance-id> </instance-info> <dataset-id>BMC.ASSET</dataset-id> </parameters> </request> </bmc-atrium-cmdb-request>
See Adapter request and response for the set-instance operation for v2.0 for the description of the request and response elements. The following figure illustrates the adapter response for the set-instance operation. XML sample of the adapter response for the set-instance operation
306
BMC Atrium Orchestrator Application Adapter for BMC Event Manager

Application adapters enable BMC Atrium Orchestrator workflow processes to perform specialized functions and to interact with external applications by providing an interface between the workflow processes and the external systems and applications. The BMC Atrium Orchestrator application adapter for BMC Event Manager interfaces with BMC Event Manager. The BMC Atrium Orchestrator application adapter for BMC Event Manager consists of an actor adapter, a monitor adapter, and workflow processes to perform the standard applications actions available through the BMC Event Manager API.
BMC Atrium Orchestrator actor adapter for BMC Event Manager

The actor adapter for BMC Event Manager (BEM) performs the following operations on BMC Service Impact Manager (BMC SIM) cells: Creates, updates, retrieves, and annotates events Enables and disables the maintenance mode The adapter operations target BMC Event Manager (BMC EM) cells. Each request to the adapter starts a sequence of requests and responses between the adapter and BMC Event Manager. When an adapter receives a request, the following sequence occurs: 1. The adapter looks up the IP address of the host cell in the mcell.dir file local to the BMC Atrium Orchestrator peer. For details about the mcell.dir file, see Communicating with a BEM cell. 2. The adapter opens a client connection to the cell specified in the request or the default cell specified in the adapter configuration. 3. The adapter registers itself with the server by issuing a register request. 4. The BMC Impact Administration Server acknowledges the registration request. The adapter receives the acknowledgment asynchronously when the underlying API invokes the processAnswer() callback method. 5. The adapter sends the actual query request to the server. The server returns the response to the query with the processAnswer() callback method. 6. The adapter sends additional requests and operations, if required, and the server returns the responses to these requests with the same processAnswer() callback method. 7. The adapter closes and unregisters requests. The BEM server acknowledges these requests. 8. The adapter closes the client connection. 9. The adapter collates all the responses from the server and returns the adapter response to the caller. 10. Adapter requests can target different BMC Event Manager cells. The adapter creates and closes a new connection for each request. 11. The adapter converts the requests into Basic Recorder of Objects in C (BAROC) formatted queries that a
307
BMC Atrium Orchestrator Application Adapters 20.11.02 11. BMC Event Manager cell understands. Note The BAROC format is a proprietary BMC Event Manager query language.
Communicating with a BEM cell

To communicate with a BMC Event Manager cell, the adapter's underlying APIs, IMAP, and IMCOMM API require access to the mcell.dir file. The mcell.dir file for the BMC Event Manager application is located at installHome\pw\server\etc in the BMC Impact Administration Server installation directory. You can use the mcell.dir file on the application (BEM) side as a reference to create or copy the mcell.dir file required by BMC Atrium Orchestrator, which is then placed on the BMC Atrium Orchestrator peer on which the adapter is enabled. The path to access this local file must be present in the adapter configuration. The mcell.dir file contains the following cell definitions: cell name host port encryption key host2 port2 Note The host2 and port2 fields in the mcell.dir file are used in high-availability setups for specifying secondary cells. If the cell name changes on the application (BEM) side, you must make corresponding changes in the mcell.dir file in BEM and the copy of the mcell.dir file that is local to the BMC Atrium Orchestrator peer to ensure that the actor adapter continues to communicate with the cell. You must disable and re-enable the adapter after the changes are made to the mcell.dir file local to the BMC Atrium Orchestrator peer. In case you also use the monitor adapter and change the cell name on the application (BEM) side, you must set up event monitoring for the new cell again as described in Setting up events for the BMC Atrium Orchestrator Monitor Adapter for BEM.
Supported versions of BEM

The adapter supports versions 7.1, 7.2.01, 7.3, and 7.4 of BMC Event Manager.
Configuring the BMC Atrium Orchestrator Application Adapter for BEM

You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with BMC Event Manager. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view and
308
save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration. Note The default name for the actor adapter is BMCEventManager.
To configure the actor adapter, monitor adapter, or both

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. Access the adapters page by clicking the Manage tab; then click the Adapters tab. 3. In the Adapters in Repository list: Select the ro-adapter-bmc-event-manager-actor check box to configure the actor adapter. Select the ro-adapter-bmc-event-manager-monitor check box to configure the monitor adapter. Select both check boxes to configure both adapters. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or skip to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. Note The Name field does not support single-quote (') and ampersand (&) characters. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements, indicated with an asterisk (*). 7. (optional) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements and attributes from the adapter user guide into the Properties text box, and then click OK. Note If the default value for an optional element is acceptable, omit the element. Do not include empty elements. e. On the Warning message that appears, click Save. This action saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the node elements required for configuring the actor adapter: Node elements for configuring the actor adapter UI label Element Description
309
Mcell Dir File Path
<mcell-dir-file-path>
Specifies the location of the mcell.dir file local to the BMC Orchestrator peer on which the adapter is enabled The mcell.dir file contains information about the cell.
For details about the mcell.dir file, see BMC Atrium Orches actor adapter for BMC Event Manager. Cell Name <cell-name>
Specifies the cell name in BMC Event Manager where the e reported
User Name
<user-name>
Specifies the user name for authenticating the BEM applica
Request Field Mapping File Location
<request-field-mapping-file-location> Specifies the location of the request field mapping file loc BMC Atrium Orchestrator peer
The request field mapping file contains information about such as custom slot name mapping, where you can specify names to be used in requests.
The slot names can be additional slots not incorporated ear existing slots that need to be identified with different names example, you can map an external name, MyMessage, to a corresponding internal name used by BMC Event Manager, follows:
<elements> <element> <external>MyMessage</external> <internal>msg</internal> </element> </elements>
If the external slot names for ID, Origin Time, Component ID Component Type, Status, Notes, Owner, or Priority are cha need to make corresponding changes in the adapter modul configuration to ensure that the wrapper validations work pr
310
Config File Location
<config-file-location>
Specifies the location of the mclient.conf file local to the B Orchestrator peer
You can use the mclient.conf file in the BMC Service Impa Manager server installation location as a reference to create the mclient.conf file required by BMC Atrium Orchestrator. mclient.conf file is then placed on the BMC Atrium Orches on which the adapter is enabled.
The mclient.conf file contains the information about the ce customized values for connection configuration parameters example, MessageBuffer parameters, Trace parameters, an
For details about the .conf files, see the BMC ProactiveNet Administrator Guide available at https://docs.bmc.com/docs/display/bppmsuite86/PDF+prod . Component Name <component-name>
Specifies the component name used for maintenance mode
<max-active-connections> Max Active Connections
Specifies the number of simultaneous active connections th made to a particular cell
If you specify a negative value, the number of simultaneous connections that can be made is unlimited. Default value: 8 <min-active-connections> Min Active Connections
Specifies the minimum number of connections that are alwa present in the connections pool
You can use this element to optimize the number of active connections in the pool, which is required to make buffering Default value: 0 The following figure shows an XML sample for configuring the actor adapter. XML sample for configuring the actor adapter
<config> <mcell-dir-file-path>/xyz/abc/lmn/mcell.dir</mcell-dir-file-path> <user-name>someuser</user-name> </config>
The following table describes the node elements required for configuring the monitor adapter: Node elements required for configuring the monitor adapter UI label Port Element <port> Description Specifies the port on which the gateway listens Required Yes
311
Gateway Name
<gateway-name>
Specifies the name of the gateway
No
Encryption Key <encryption-key> Specifies the encryption key used to encrypt events Yes
Note The configuration information that you specify for the monitor adapter must match that specified in the incomm.conf and mcell.dir files located on the BEM server. The following figure shows an XML sample for configuring the monitor adapter. XML sample for configuring the monitor adapter
<config> <port>1859</port> <gateway-name>BEMGW</gateway-name> <encryption-key>mc</encryption-key> </config>
BMC Atrium Orchestrator Application Adapter for BEM module

Top-level processes for BMC Atrium Orchestrator Application Adapter for BEM
The top-level processes perform high-level operations and call specialized processes in the subdirectories of the v7.1 and v7.3 directories. The top-level processes in the Project Explorer window execute the following version-specific processes. Create Items Find Items Perform Operations Update Items
Process inputs for BMC Atrium Orchestrator Application Adapter for BEM
The following table describes the input elements used by a process in the adapter module.
Process input elements Element <adapter name> Description Specifies the name of the adapter that handles the request Required Conditional; not required if the adapter is enabled using the default adapter name Yes
<items>
Contains the <item> XML elements used to execute the events
312
<item type>
Specifies the type of process that must be executed
Yes Yes
<version> Specifies the version directory from which the process should be executed See Mapping of version directory information with BMC Event Manager versions for information about compatibility of processes in the v7.1 and v7.3 directories with BMC Event Manager versions. Valid values: 7.1, 7.3
Create Items process for BMC Atrium Orchestrator Application Adapter for BEM
The Create Items process enables you to create one or more events based on the information specified in the request. The valid value for <item type> is event. The following figure shows a sample <items> XML element for the Create Items process. <items> XML element for the Create Items process
<items> <item> <connection-parameters> <user-name>user</user-name> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Message</name> <value>TINIMaINI</value> </argument> <argument> <name>Category</name> <value>OPERATIONS_MANAGEMENT</value> </argument> <argument> <name>Severity</name> <value>info</value> </argument> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Host</name> <value>s-17124</value> </argument> <argument> <name>Component ID</name> <value>EM_Cell_Server -Dev1</value> </argument> <argument> <name>Rule</name> <value>testMCTOOLRULE</value>
313
</argument> <argument> <name>Class</name> <value>MC_CELL_PARSE_ERROR</value> </argument> <argument> <name>Account</name> <value>testaccount</value> </argument> <argument> <name>Object Class</name> <value>testobjclass</value> </argument> <argument> <name>Parameter</name> <value>testparameter</value> </argument> <argument> <name>Object</name> <value>testobject</value> </argument> <argument> <name>Parameter Threshold</name> <value>testParameterThreshold</value> </argument> <argument> <name>SMC Alias</name> <value>EM_Cell_Server_1_India-Dev1</value> </argument>
314
</arguments> </item> </items>
Find Items process for BMC Atrium Orchestrator Application Adapter for BEM
The Find Items process enables you to retrieve the events matching the search criteria specified in the request. The Find Items process can perform the following activities: Retrieve Event by Date Retrieve Events by Component Retrieve Events by ID Retrieve Events The valid values for <item type> are: date component ID retrieve The following figure shows a sample <items> XML element for the Find Items process. <items> XML element for the Find Items process
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component Type</name> <value>BMC_AdministrationApplication</value> </argument> <argument> <name>Class</name> <value>EVENT</value> </argument> </arguments> </item> </items>
Note You can retrieve events by specifying the event class, EVENT specified in the Find Items request as shown in the preceding figure. If you do not specify a class, all the events corresponding to all the classes are retrieved. For example, if you specify the event class as EVENT, the Find Items process retrieves events of the EVENT event class. It does not retrieve events in subclasses of EVENT.
315
Perform Operations process for BMC Atrium Orchestrator Application Adapter for BEM
The Perform Operations process performs the following maintenance mode operations on the specified components: Disable Event Reporting Resume Event Reporting The valid values for <item type> are disable-event-reporting and resume-event-reporting. The following figure shows a sample <items> XML element for the Perform Operations process. <items> XML element for the Perform Operations process
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell - ESG1</component-name> </item> </items>
Update Items process for BMC Atrium Orchestrator Application Adapter for BEM
The Update Items process enables you to retrieve the events matching the search criteria and update the events using the values specified in the request. The Update Items process can perform the following activities: Acknowledge Event Annotate Event Assign Event Close Event Reopen Event Set Action Result (This process is valid for BMC Event Manager 7.3 and later.) Set Event Priority Update Event The valid values for <item type> are: acknowledge annotate assign close reopen set action result (This value is valid for BMC Event Manager 7.3 and later.) prioritize update The following figure shows a sample <items> XML element for the Update Items process. <items> XML element for the Update Items process
316
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component Type</name> <value>BMC_AdministrationApplication</value> </argument> </arguments> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>message text</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> </item> </items>
SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BEM
The processes in the SetupValidation directory contain sample values for request elements. These sample values can be quickly changed to reflect the values in your environment. A process is provided to test each supported method of executing operations in BMC Event Manager.
Utilities directory for BMC Atrium Orchestrator Application Adapter for BEM
The Utilities directory contains constructor processes that you can use to create the complex XML inputs required in the functional version-specific processes. The constructor processes are organized into general utilities and subdirectories that correspond to the supported operation types.
Version directories for BMC Atrium Orchestrator Application Adapter for BEM
The v7.1 and v7.3 directories contain functional processes specific to a version of BMC Event Manager. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of the operation. In the v7.1 directory, the functional processes are specific to BMC Event Manager 7.1.
317
In the v7.3 directory, the functional processes are specific to BMC Event Manager 7.3. The v7.3 directory contains all the processes in the v7.1 directory and the Set Action Result process, which is specific to v7.3. The following table maps the version directory information with BMC Event Manager versions. Mapping of version directory information with BMC Event Manager versions Version Compatible with BMC directory Event Manager 7.1? v7.1 v7.3 Yes No Compatible with BMC Event Manager 7.2.01? Yes No Compatible with BMC Event Manager 7.3? Yes Yes Compatible with BMC Event Manager 7.4? Yes Yes
Actor adapter requests and responses for BMC Atrium Orchestrator Application Adapter for BEM
The actor adapter can perform different API calls on BMC Event Manager. The adapter requests contain values that are used to execute API calls. The set of values used to make each API call is referred to as an operation. The available operations for the actor adapter are: Create Event Maintenance mode operations Retrieve Event Update Event You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity.
Adapter request and response for the Create operation for BMC Atrium Orchestrator Application Adapter for BEM
This section illustrates the adapter request and response for the Create Event operation and describes the elements used in the request. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Create Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Create Event operation enables you to create events based on the information specified in the request. The following figure shows a sample <items> XML element for the Create Event operation.
318
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name></name> <value></value> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Create Event operation.
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <operation-name>create-event</operation-name> <arguments> <argument> <name>Message</name> <value>TIKOPsIKO1</value> </argument> <argument> <name>Category</name> <value>OPERATIONS_MANAGEMENT</value> </argument> <argument> <name>Severity</name> <value>info</value> </argument> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Host</name> <value>s-17124</value> </argument> <argument> <name>Component ID</name> <value>EM_Cell_Server_1-Dev1</value> </argument> <argument> <name>Rule</name> <value>testMCTOOLRULE</value>
319
</argument> <argument> <name>Class</name> <value>MC_CELL_PARSE_ERROR</value> </argument> <argument> <name>Account</name> <value>testaccount</value> </argument> <argument> <name>Object Class</name> <value>testobjclass</value> </argument> <argument> <name>Parameter</name> <value>testparameter</value> </argument> <argument> <name>Object</name> <value>testobject</value> </argument> <argument> <name>Parameter Threshold</name> <value>testParameterThreshold</value> </argument> <argument> <name>SMC Alias</name> <value>EM_Cell_Server_1_India-Dev1</value>
320
</argument> </arguments> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Create Event operation. Adapter response for the Create Event operation
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-response> <Modified>1205224197</Modified> <Status>OPEN</Status> <Severity>INFO</Severity> <Owner></Owner> <Component_ID>EM_Cell_Server_1-Dev1</Component_ID> <Host>s-17124</Host> <Origin_Time>0</Origin_Time> <Message>TIKOPsIKO1</Message> <Priority>PRIORITY_2</Priority> <Time_To_Close>0</Time_To_Close> <Component_Type></Component_Type> <Service></Service> <Received>1205224197</Received> <Occurances>0</Occurances> <Arrived>1205224197</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1205224197</Occurred> <Host_Address></Host_Address> <Location>Unknown</Location> <ID>mc.1828.1210339483775</ID> <Class>MC_CELL_PARSE_ERROR</Class> <mc-tool>bem-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>ro-adapter-BMC-event-manager-actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmceventmanageractoradapter </mc-tool-address> <Rule>testMCTOOLRULE</Rule> <mc-tool-time>1214236542</mc-tool-time> <Account>testAccount</Account> <Object_Class>testObjectClass</Object_Class> <Parameter>testParameter</Parameter> <Object>testObject</Object> <Parameter_Threshold>testParameterThreshold</Parameter_Threshold> <SMC_Alias>EM_Cell_Server_1_India-Dev1</SMC_Alias> </query-response> </event-manager-query-response> </bmc-event-manager-response>
321
Adapter requests and responses for the Maintenance Mode operations for BMC Atrium Orchestrator Application Adapter for BEM
This section illustrates the adapter requests and responses for the following Maintenance Mode operations and describes the elements used in the requests: Disable Event Reporting Resume Event Reporting Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Disable Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BEM
The Disable Reporting operation enables you to disable reporting on a cell specified in the request. Note This operation requires propagation rules to be set in BMC Event Manager. For more information, see Propagation rules for maintenance mode. The following figure shows a sample <items> XML element for the Disable Event Reporting operation. < items > XML element for the Disable Event Reporting operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell -Dev1</component-name> </item> </items>
The following figure shows a sample adapter request for the Disable Event Reporting operation.
<bmc-event-manager-request> <connection-parameters> <cell-name>somecell</cell-name> <timeout-secs>100</timeout-secs> <user-name>someuser</user-name> </connection-parameters> <operation-name>disable-event-reporting</operation-name> <component-name>EM Cell-Dev1</component-name> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Disable Event Reporting operation
322
Adapter response for the Disable Event Reporting operation

<bmc-event-manager-response> <response-metadata> <status>success</status> </response-metadata> <event-manager-maintenance-mode-response> <maintenance-mode-responses> <maintenance-mode-response> <component-name>EM Cell -Dev1</component-name> <component-id>252</component-id> <return-code>0</return-code> <return-message></return-message> </maintenance-mode-response> </maintenance-mode-responses> </event-manager-maintenance-mode-response> </bmc-event-manager-response>
Resume Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BEM
The Resume Event Reporting operation enables you to resume the reporting on a cell specified in the request. Note This operation requires propagation rules to be set in BMC Event Manager. For more information, see Propagation rules for maintenance mode. The following figure shows a sample <items> XML element for the Resume Event Reporting operation.
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell Dev1</component-name> </item> </items>
The following figure shows a sample adapter request for the Resume Event Reporting operation. Sample adapter request for the Resume Event Reporting operation
323
<bmc-event-manager-request> <connection-parameters> <cell-name>somecell</cell-name> <timeout-secs>100</timeout-secs> <user-name>someuser</user-name> </connection-parameters> <operation-name>resume-event-reporting</operation-name> <component-name>EM Cell -Dev1</component-name> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Resume Event Reporting operation.
<bmc-event-manager-response> <response-metadata> <status>success</status> </response-metadata> <event-manager-maintenance-mode-response> <maintenance-mode-responses> <maintenance-mode-response> <component-name>EM Cell -Dev1</component-name> <component-id>252</component-id> <return-code>0</return-code> <return-message></return-message> </maintenance-mode-response> </maintenance-mode-responses> </event-manager-maintenance-mode-response> </bmc-event-manager-response>
Adapter requests and responses for the Retrieve operations for BMC Atrium Orchestrator Application Adapter for BEM
This section illustrates the adapter requests and responses for the following Retrieve operations and describes the elements used in the requests. Retrieve Events Retrieve Event by Date Retrieve Events by Component Retrieve Events by ID You can execute additional operations with the following search criteria: Category Component ID Component Type Date (Origin Time) Host Host Address Host Class Location Message Occurrences (Count) Owner Priority
324
Service Severity Status Time to Close (Duration) Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Retrieve Events operation for BMC Atrium Orchestrator Application Adapter for BEM
The Retrieve Events operation enables you to retrieve events that match all the search criteria specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events operation. <items> XML element for the Retrieve Events operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>My Event ID</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Component Type</name> <value>My Component Type</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Component ID</name> <value>My Component ID</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Category</name> <value>My Category</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Time to Close</name> <value>150</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Host</name> <value>My Host Name</value> <filter-criteria>equals</filter-criteria>
325
</argument> <argument> <name>Host Class</name> <value>Computer</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Host Address</name> <value>10.10.75.167</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Location</name> <value>synapse.com</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Message</name> <value>User1 was here</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Owner</name> <value>user</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Priority</name> <value>2 - High</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Severity</name> <value>CRITICAL</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Service</name> <value></value> </argument> <argument> <name>Status</name> <value>Acknowledged</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Occurences</name> <value>1</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Origin Time</name> <value>12/13/07 3:46 AM</value> <filter-criteria>equals</filter-criteria> </argument>
326
The following figure shows a sample adapter request for the Retrieve Events operation.
<bmc-event-manager-request> <operation-name>retrieve-event</operation-name> <connection-parameters> <cell-name>somecell</cell-name> <timeout-secs>100</timeout-secs> <user-name>someuser</user-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>mc.1828.1210339483775</value> </argument> <argument> <name>Severity</name> <value>Info</value> </argument> </arguments> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Retrieve Events operation. Adapter response for the Retrieve Events operation
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-executed>select [mc_date_modification, status, severity, mc_owner, mc_smc_id, mc_host, mc_notes, mc_incident_time, msg, mc_priority, duration, mc_smc_type, mc_service, mc_local_reception_time, mc_action_count, mc_arrival_time, mc_host_class, mc_event_category, date_reception, mc_host_address, mc_location, mc_ueid, CLASS, mc-tool, adapter-host, mc-tool-class, mc-tool-address, mc-tool-rule, mc-tool-time, mc_account, mc_object_class, mc_parameter, mc_object, mc_parameter_threshold, mc-smc-alias] from EVENT where [$THIS.mc_ueid equals 'mc.1828.1210339483775'] END</query-executed> <query-response> <Modified>1210346577</Modified> <Status>CLOSED</Status> <Severity>INFO</Severity> <Owner><Owner> <Component_ID>EM_Cell_Server_1 -Dev1</Component_ID> <Host>s-17124</Host> <Notes>0x482915dcuserTEST NOTES MESSAGE0x48290d85userTEST NOTES
327
MESSAGE0x4824b97fuserSETUP VALIDATION TEST NOTE</Notes> <Origin_Time>0</Origin_Time> <Message>TIKOPsIKO1</Message> <Priority>PRIORITY_2</Priority> <Time_to_Close>7104</Time_to_Close> <Component_Type></Component_Type> <Service></Service> <Received>1210339473</Received> <Occurences>0</Occurences> <Arrived>1210339473</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1210339473</Occurred> <Host_address></Host_address> <Location>Unknown</Location> <ID>mc.1828.1210339483775</ID> <CLASS>MC_CELL_PARSE_ERROR</CLASS> <mc-tool>bem-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>ro-adapter-BMC-event-manager-actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmceventmanageractoradapter </mc-tool-address> <mc-tool-rule>testMCTOOLRULE</mc-tool-rule> <mc-tool-time>1214236542</mc-tool-time> <mc_account>testAccount</mc_account> <mc_object_class>testObjectClass</mc_object_class> <mc_parameter>testParameter</mc_parameter> <mc_object>testObject</mc_object> <mc_parameter_threshold>testParameterThreshold</mc_parameter_threshold> <mc-smc-alias>EM_Cell_Server_1_India-Dev1</mc-smc-alias>
328
</query-response> </event-manager-query-response> </bmc-event-manager-response>
Retrieve Event by Date operation for BMC Atrium Orchestrator Application Adapter for BEM
The Retrieve Event by Date operation enables you to retrieve events matching the origin time specified in the request. The following figure shows a sample <items> XML element for the Retrieve Event by Date operation. <items> XML element for the Retrieve Event by Date operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Origin Time</name> <value>10/30/07 12:47 PM</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Retrieve Event by Date operation. Sample adapter request for the Retrieve Event by Date operation
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Origin Time</name> <value>10/30/07 12:47 PM</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-event-manager-request>
329
The following figure illustrates the adapter response for the sample Retrieve Event by Date operation.
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>2</count> </response-metadata> <event-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_incident_time greater_or_equals '1295516760' AND $THIS.mc_incident_time smaller_or_equals '1295516820'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host>2k3std64bitvm2</Host> <adapter_host>2k3std64bitvm2</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.84</mc_tool_address> <Account></Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>OK</Severity> <Modified>1295516770</Modified> <Parameter_Threshold></Parameter_Threshold> <Host_Address>10.128.248.84</Host_Address> <ID>mc.india.d380462.0</ID> <mc_tool_time>1295516770</mc_tool_time> <Parameter></Parameter> <Origin_Time>1295516768</Origin_Time> <mc_tool>Security</mc_tool> <Object>adapter</Object> <mc_tool_class>EventLog</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID></Component_ID> <Message>Successful Network Logon: User Name: Domain: Logon ID: (0x0,0x536CABD) Logon Type: 3 Logon Process: NtLmSsp Authentication Package: NTLM Workstation Name: BMC-VARUNGUPTA Logon GUID: -
330
Caller User Name: Caller Domain: Caller Logon ID: Caller Process ID: Transited Services: Source Network Address: 10.128.249.22 Source Port: 0 </Message> <Location>Unknown</Location> <Rule></Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516768</Occurred> <Category></Category> <Class>WIN_EL_SECURITY</Class> <Received>1295516770</Received> <Host_Class></Host_Class> <Arrived>1295516770</Arrived> <Object_Class></Object_Class> <SMC_Alias></SMC_Alias> </query-response>
331
</query-responses> </event-manager-query-response> </bmc-event-manager-response>
Retrieve Events by Component operation for BMC Atrium Orchestrator Application Adapter for BEM
The Retrieve Events by Component operation enables you to retrieve events matching the component type or component ID specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events by Component ID operation. <items> XML element for the Retrieve Event by Component ID operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component ID</name> <value>EM_Cell_Server_1_India-Dev1</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Retrieve Events by Component operation. Sample adapter request for the Retrieve Events by Component ID operation
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> <connection-parameters> <arguments> <argument> <name>Component ID</name> <value>EM_Cell_Server_1_India-Dev1</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Retrieve Event by Component ID operation.
332
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>3</count> </response-metadata> <event-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_smc_id equals 'EM_Cell_Server_1_India-Dev1'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>MINOR</Severity> <Modified>1295516607</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>India.BEMActor.9103955</ID> <mc_tool_time>1295516571</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>viresh smoke test</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516607</Occurred> <Category>OPERATIONS_MANAGEMENT</Category> <Class>MC_CELL_PARSE_ERROR</Class> <Received>1295516607</Received> <Host_Class></Host_Class> <Arrived>1295516607</Arrived>
333
<Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>MINOR</Severity> <Modified>1295516786</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BEMActor.5396431</ID> <mc_tool_time>1295516752</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>test message</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516786</Occurred> <Category>OPERATIONS_MANAGEMENT</Category> <Class>MC_CELL_PARSE_ERROR</Class> <Received>1295516786</Received> <Host_Class></Host_Class> <Arrived>1295516786</Arrived> <Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>MINOR</Severity> <Modified>1295520241</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BEMActor.6500802</ID>
334
<mc_tool_time>1295520206</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>test message 2</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295520241</Occurred> <Category>OPERATIONS_MANAGEMENT</Category> <Class>MC_CELL_PARSE_ERROR</Class> <Received>1295520241</Received> <Host_Class></Host_Class> <Arrived>1295520241</Arrived> <Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response>
335
</query-responses> </event-manager-query-response> </bmc-event-manager-response>
Retrieve Events by ID operation for BMC Atrium Orchestrator Application Adapter for BEM
The Retrieve Events by ID operation enables you to retrieve events matching the event ID specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events by ID operation. <items> XML element for the Retrieve Events by ID operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>india.BEM.6500802</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for Retrieve Events by ID operation. Sample adapter request for the Retrieve Events by ID operation
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>india.BEM.6500802</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Retrieve Event by ID operation.
336
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_ueid equals 'india.BEMActor.15243905'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account></Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>CRITICAL</Severity> <Modified>1295510258</Modified> <Parameter_Threshold></Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BEMActor.15243905</ID> <mc_tool_time>1295510224</mc_tool_time> <Parameter></Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object></Object> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID></Component_ID> <Message>Create Items</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_2</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295510258</Occurred> <Category></Category> <Class>EVENT</Class> <Received>1295510258</Received> <Host_Class></Host_Class> <Arrived>1295510258</Arrived>
337
<Object_Class></Object_Class> <SMC_Alias></SMC_Alias> </query-response>
338
</query-responses> </event-manager-query-response> </bmc-event-manager-response
Adapter requests and responses for the Update operations for BMC Atrium Orchestrator Application Adapter for BEM
This section illustrates the adapter requests and responses for the following Update operations and describes the elements used in the requests: Update Event Acknowledge Event Annotate Event Assign Event Close Event Reopen Event Set Event Priority Set Action Result To keep track of what operations took place on an event on the cells, the Assign Event, Close Event, Reopen Event, and Set Event Priority operations update the Operation History tab of BMC Impact Explorer. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Update Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Update Event operation enables you to update events retrieved using the search criteria specified in the request. The following figure shows a sample <items> XML element for the Update Event operation. <items> XML element for the Update Event operation
339
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>test1</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Update Event operation. Sample adapter request for the Update Event operation
340
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>Insert message here</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the adapter response for the sample Update Event operation. Adapter response for the Update Event operation
341
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-executed>select [event_handle, mc_date_modification, status, severity, mc_owner, mc_smc_id, mc_host, mc_incident_time, msg, mc_priority, duration, mc_smc_type, mc_service, mc_local_reception_time, mc_action_count, mc_arrival_time, mc_host_class, mc_event_category, date_reception, mc_host_address, mc_location, mc_ueid, CLASS, mc-tool, adapter-host, mc-tool-class, mc-tool-address, mc-tool-rule, mc-tool-time, mc_account, mc_object_class,mc_parameter, mc_object, mc_parameter_threshold, mc-smc-alias] from EVENT where [$THIS.mc_incident_time greater_or_equals '1193728620' AND $THIS.mc_incident_time smaller_or_equals '1193728680'] END</query-executed> <query-response> <event-handle>124919</event-handle> <Modified>1199286532</Modified> <Status>ACK</Status> <Severity>OK</Severity> <Owner>SOMEONE</Owner> <Component_ID>IAS_Admin@india-dev1</Component_ID> <Host>india-dev1</Host> <Origin_Time>1193728671</Origin_Time> <Message>TEST MESAGE</Message> <Priority>PRIORITY_5</Priority> <Time_to_Close>5517863</Time_to_Close> <Component_Type>BMC_AdministrationApplication</Component_Type> <Service></Service> <Received>1196423411</Received> <Occurences>1</Occurences> <Arrived>1196423411</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1193728671</Occurred> <Host_Address></Host_Address> <Location>Unknown</Location> <ID>mc.Admin.74ff8f3.0</ID> <CLASS>MC_CELL_PARSE_ERROR</CLASS> <mc-tool>bem-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>ro-adapter-BMC-event-manager-actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmceventmanageractoradapter</mc-tool-address> <mc-tool-rule>testMCTOOLRULE</mc-tool-rule> <mc-tool-time>1214236542</mc-tool-time> <mc_account>testAccount</mc_account> <mc_object_class>testObjectClass</mc_object_class> <mc_parameter>testParameter</mc_parameter> <mc_object>testObject</mc_object> <mc_parameter_threshold>testParameterThreshold</mc_parameter_threshold> <mc-smc-alias>EM_Cell_Server_1_India-Dev1</mc-smc-alias> </query-response> </event-manager-query-response>
342
Acknowledge Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Acknowledge Event enables you to acknowledge events retrieved using the search criteria specified in the request. The following figure shows a sample <items> XML element for the Acknowledge Event operation. <items> XML element for the Acknowledge Event operation
<items> <item> <connection-parameters> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BMCEventManager.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>acknowledged</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Acknowledge Event operation.
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>acknowledged</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
343
The following figure illustrates the response for the sample Acknowledge Event operation. Adapter response for the Acknowledge Event operation
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>ACK</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCEventManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353562</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Notes /> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCEventManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BMCEventManager.1232352705131</ID> </query-response> </query-responses> </event-manager-query-response> </bmc-event-manager-response>
344
Annotate Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Annotate Event operation adds a message to the events retrieved with the search criteria specified in the request. The following figure shows a sample <items> XML element for the Annotate Event operation. <items> XML element for the Annotate Event operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Notes</name> <value>User1 Annotating an event</value> </argument> </update-arguments> <arguments> <argument> <name>ID</name> <value>mc.akatkar-pun-01.97ff50a.0</value> </argument> </arguments> <operation-name>update-event</operation-name> </item> </items>
The following figure shows a sample adapter request for the Annotate Event operation.
345
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Notes</name> <value>User1 Annotating an event</value> </argument> </update-arguments> <arguments> <argument> <name>ID</name> <value>mc.akatkar-pun-01.97ff50a.0</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the response for the Annotate Event operation. Adapter response for the Annotate Event operation
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query>ntadd 0 's-17127.BMCEventManager.1232352705131' "TEST NOTES MESSAGE"</query> <query-responses> <notes> <note> <create-date>1232353678000</create-date> <user-name>RBA BEM Adapter</user-name> <message>TEST NOTES MESSAGE</message> </note> </notes> </query-responses> </event-manager-query-response> </bmc-event-manager-response>
Assign Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Assign Event operation enables you to assign events that are retrieved to a specified user. The following figure shows a sample <items> XML element for the Assign Event operation.
346
<items> <item> <connection-parameters> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BMCEventManager.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Owner</name> <value>SOMEONE</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Assign Event operation.
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Owner</name> <value>user</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the response for the sample Assign Event operation. Adapter response for the Assign Event operation
347
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>ASSIGNED</Status> <Owner>SOMEONE</Owner> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCEventManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353757</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BEM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCEventManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BMCEventManager.1232352705131</ID> </query-response> </query-responses> </event-manager-query-response> </bmc-event-manager-response>
Close Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Close Event operation enables you to close events retrieved by the request. The following figure shows a sample <items> XML element for the Close Event operation.
348
<items> <item> <connection-parameters> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BMCEventManager.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>Closed</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Close Event operation.
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>Closed</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the response for the sample Close Event operation.
349
<bmc-event-manager-response> <response-metadata> <count>1</count> <query-response> <mc_tool_time>1232352704</mc_tool_time> <Priority>PRIORITY_2</Priority> <Rule>Rule_testing</Rule> <mc_tool_address>10.10.75.131-CDP1-BMCEventManager</mc_tool_address> <Modified>1232353757</Modified> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BEM Adapter18 TEST NOTES MESSAGE</Notes> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <mc_tool>BMCEventManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <ID>s-17127.BMCEventManager.1232352705131</ID> </query-response> </bmc-event-manager-response>
Reopen Event operation for BMC Atrium Orchestrator Application Adapter for BEM
The Reopen Event operation enables you to reopen events that are retrieved using the search criteria. Reopening an event clears the current event owner for the event. The following figure shows a sample <items> XML element for the Reopen Event operation.
<items> <item> <connection-parameters> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BMCEventManager.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>Open</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Reopen Event operation. Sample adapter request for the Reopen Event operation
350
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>Open</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure illustrates the response for the sample Reopen Event operation.
351
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>OPEN</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCEventManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353915</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BEM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>1263</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCEventManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BMCEventManager.1232352705131</ID> </query-response> </query-responses> </event-manager-query-response> </bmc-event-manager-response>
Set Event Priority operation for BMC Atrium Orchestrator Application Adapter for BEM
The Set Event Priority operation sets the priority of the events that are retrieved using the search criteria. The following figure shows a sample <items> XML element for the Set Event Priority operation.
352
<items> XML element for the Set Event Priority operation

<items> <item> <connection-parameters> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Set Event Priority operation. Sample adapter request for the Set Event Priority operation
<bmc-event-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-agruments> <argument> <name>Priority</name> <value>2 - High</value> </argument> </update-arguments> <operation-name>update-event</operation-name> </bmc-event-manager-request>
The following figure shows the response for the sample Set Event Priority operation.
353
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <event-manager-query-response> <query-responses> <query-response> <Severity>OK</Severity> <Status>OPEN</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Message testing</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCEventManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232354163</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>ro-adapter-BMC-event-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BEM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>1263</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCEventManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BMCEventManager.1232352705131</ID> </query-response> </query-responses> </event-manager-query-response> </bmc-event-manager-response>
Set Action Result operation for BMC Atrium Orchestrator Application Adapter for BEM
The Set Action Result operation enables you to set the result of a Cell-Action-Result event on BMC Event Manager. The Set Action Result operation is supported by BMC Event Manager v7.3 and later.
354
The monitor adapter captures the remote action event information sent by BMC Event Manager. This information is processed by BMC Atrium Orchestrator workflows for executing actions. The action results are forwarded by the actor adapter to BMC Event Manager.
Configuring the cell for extended events
You must set up BMC Event Manager to generate extended events for the Set Action Result operation.
To set up the cell to generate extended events
1. Add an entry for the monitor adapter in the $ MCELL_HOME/etc/mcell.dir file, in the following format: cell monitorName mc hostName/portNumber monitorName is the name of the monitor adapter mc is the encryption key portNumber is the port on which the hostName computer listens 2. Add an action rule to the cell Knowledge Base (KB) by creating a test_rba.mrl file in the $ MCELL_HOME /etc/ cell /bin/ directory. cell is the name of the cell The test_rba.mrl file must contain the following action rule: action test_rba_1 : EVENT($E) admin_execute( monitorName ,$E, action1 ,[], YES ); END monitorName is the name of the monitor adapter action1 is the action to be performed on the event within BMC Atrium Orchestrator YES indicates that the action result event is updated with the result of the action when the event terminates in BMC Atrium Orchestrator 3. Compile the cell KB: mccomp -n cell1 The cell name is cell1. 4. Restart the cell: mcell -n cell1 5. Test by sending one or more events to the cell: mposter -n cell1 -a EVENT -m 'test event 1' 6. Trigger the action on the event. A new event of the class, MC_CELL_ACTION_RESULT is generated. The following figure shows a sample <items> XML element for the Set Action Result operation.
355
<items> <item> <connection-parameters> <timeout-secs>100</timeout-secs> <cell-name>realops-qa13</cell-name> </connection-parameters> <arguments> <argument> <name>ActionResultId</name> <value>1</value> </argument> <argument> <name>ExitCode</name> <value>0</value> </argument> <argument> <name>OutputText</name> <value>testaccount123</value> </argument> <argument> <name>ErrorText</name> <value>testobjectclass123</value> </argument> </arguments> </item> </items>
Note The request for the Set Action Result operation returns a response that does not query the actual updated event. Hence, the count in the XML response is 0, even if the event is successfully updated. Also, no event fields are displayed in the XML response.
The following figure shows the sample adapter request for the Set Action Result operation.
356
<bmc-event-manager-request> <connection-parameters> <timeout-secs>100</timeout-secs> <cell-name>realops-qa13</cell-name> </connection-parameters> <arguments> <argument> <name>ActionResultId</name> <value>1</value> </argument> <argument> <name>ExitCode</name> <value>0</value> </argument> <argument> <name>OutputText</name> <value>testaccount123</value> </argument> <argument> <name>ErrorText</name> <value>testobjectclass123</value> </argument> </arguments> <operation-name>set-action-result</operation-name> </bmc-event-manager-request>
Sample adapter request for the Set Action Result operation (part ? of ?) Note You must enclose argument values containing special characters or XML code within CDATA as follows: <value> <![CDATA[ complexArgumentValue ]]> </value> For the Set Action Result operation, the OutputText and ErrorText arguments might contain special characters or XML code. The following figure illustrates the response for the sample Set Action Result operation. Adapter response for the Set Action Result operation
<bmc-event-manager-response> <response-metadata> <status>success</status> <count>0</count> </response-metadata> <event-manager-query-response> <query-responses /> </event-manager-query-response> </bmc-event-manager-response>
BMC Atrium Orchestrator Monitor Adapter for BEM

357
The monitor adapter receives events from BMC Event Manager and other sources, like the msend command, and Impact Integration Web Server (IIWS) on the BEM gateway. You must specify the gateway name, port, and encryption key in the monitor adapter configuration. These elements are the interface to the BEM gateway definitions. Therefore, these elements must match the BEM gateway definitions in the mcell.dir and incomm.conf files to capture the events sent to the monitor adapter. To use the monitor adapter, you must configure cells to forward events to the gateway in the BMC Impact Administration Server environment. For details about the configuration elements for the monitor adapter, see the Node elements for configuring the monitor adapter table. Note BMC Atrium Orchestrator 20.11.01 and later is integrated with BMC Event Manager within the BMC ProactiveNet Performance Manager solution. For information about configuring the BMC Event Manager cell to send events to the monitor adapter, see the BMC ProactiveNet Administrator Guide. The monitor adapter handles the events in the following sequence: 1. The monitor adapter listens on the BEM gateway that is set up on the BEM server to detect and handle events. 2. The rules in the module configuration are then triggered by the event to handle the designed workflow.
Setting up events for the BMC Atrium Orchestrator Monitor Adapter for BEM
he monitor adapter does not use the mcell.dir file that is local to the BMC Atrium Orchestrator peer. To enable propagation of events from the cells to the gateway, you must make changes to the mcell.dir file on BEM. However, if you need to change the listener port in the monitor adapter configuration, you must also make this change in the mcell.dir file on the BEM server.
To enable propagation of events from the BEM cells to the gateway

1. Create the gateway.imcomm file on the BEM server in the $MCELL_HOME/etc directory. 2. Add the following line to define the gateway in the mcell.dir file: Example gateway.imcomm gw mc 10.10.75.88:1859 The variables are defines as follows: gw: gateway name mc: encryption key 10.10.75.88: IP address of the peer local to BMC Atrium Orchestrator 1859: port on which the monitor adapter listens for events 3. Restart the mcell services and the Impact Integration Web Server (IIWS) service. Note Starting with BMC Event Manager version 7.4, the IIWS service is renamed as Impact Integration Web Service.
The following figure illustrates a sample gateway.imcomm file. Sample gateway.imcomm file
358
#cond.new=propagate #cond.mod=always #drop.mod=[] #drop.new=[] #add.mod=[] #add.new=[] slots.new=[$ALL] slots.mod=[mc_ueid, $MODS] #modify.mod=[] #--------------------------------------------------------------# Format parameters - MAY NOT BE MODIFIED or message will be not acknowledged by ImGateway #--------------------------------------------------------------init.new=$CLASS;\n init.mod=modify $GHANDLE;\n body=\t$NAME=$VALUE;\n term=END\n #separator= #quoatable=<standard MRL quotation rules> #openquote=' #closequote=' #escapequote='
Propagating events from the cells to the gateway for the BMC Atrium Orchestrator Monitor Adapter for BEM
You must set up a propagation rule to ensure that events are propagated from the cells to the gateway.
To set up the propagation rule

1. Copy the gatewayim.mrl file to $MCELL_HOME/etc/cellName/kb/rules. 2. Set the name of the relevant gateway ( gw1 ) in the gatewayim.mrl file as shown in the following sample:
propagate p:EVENT to gw1 END
3. Add an entry for gatewayim in the .load file at $MCELL_HOME/etc/cellName/kb/rules to load the gatewayim.mrl file. 4. Navigate to the $MCELL_HOME/etc/cellName/kb directory and compile the knowledge base by executing the following command: mccomp manifest.kb 5. Restart the cell. For more information about propagation rules, see Propagation rules for the maintenance mode for the BMC Atrium Orchestrator Monitor Adapter for BEM.
Module configuration for BMC Event Manager

Module configuration maps external slot names (as used in the XML requests and responses) to slot names that are referenced by the wrapper validations. You can customize external slot names by specifying a custom mapping file in the adapter configuration and use those slot names for validations.
359
Note If you specify a custom mapping file, ensure that you change the corresponding external name in the module configuration for the validations to work as desired.The module configuration lists only the slot names that are used in the validations. Module configuration contains a BMC_Event_Manager group that defines static string mappings of certain slot names mapped to their external values. You can modify the external slot names by specifying the slot names in the custom slot name mapping file referenced using the <request-field-mapping-file-location> element of the adapter configuration. For details about the configuration elements for the actor adapter, see Node elements for configuring the actor adapter. Note Change the module configuration only if the changed slot names are present in the module configuration.
Propagation rules for the maintenance mode for the BMC Atrium Orchestrator Monitor Adapter for BEM
Propagation rules ensure that event reporting does not occur on components in the maintenance mode. By default, a propagation rule is defined in the gatewayim.mrl file for each component that is installed on BMC Event Manager. The gatewayim.mrl file is part of BMC Event Manager. For example, suppose a workflow queries the change management system and detects that an active change is being worked on. To avoid reporting events on the component when it is in maintenance mode, you configure a propagation rule in the gatewayim.mrl file. Note By default, a propagation rule allows event reporting on configured components. To use an adapter request for the disable-event-reporting operation or resume-event-reporting operation in a process, a propagation rule must be set up. The information for the propagation rule is set in the gatewayim.mrl file.
Sample propagation rule for maintenance mode

$CI.mc_udid == $EV.mc_smc_id AND $EV.mc_smc_id \!= ''
BMC Atrium Orchestrator Monitor Adapter for BEM Event

The monitor adapter receives traps published by BMC Event Manager. To perform actions related to traps, you design processes and implement rules. The following figure illustrates a sample monitor adapter event.
360
<event> <date-reception><![CDATA[1200910937]]></date-reception> <mc-arrival-time><![CDATA[1200910937]]></mc-arrival-time> <mc-local-reception-time><![CDATA[1200910937]]></mc-local-reception-time> <severity><![CDATA[CRITICAL]]></severity> <msg><![CDATA[HI THERE]]></msg> <mc-priority><![CDATA[PRIORITY_1]]></mc-priority> <mc-ueid><![CDATA[mc.Dev1.7947259.0]]></mc-ueid> <date><![CDATA[20080121155217.000000+330]]></date> <mc-date-modification><![CDATA[1200910937]]></mc-date-modification> <mc-location><![CDATA[Unknown]]></mc-location> <mc-history><![CDATA[['Dev1:97522']]]></mc-history> </event>
Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BEM

This section lists troubleshooting specific to BEM.
Event with WARNING severity received by the BMC Atrium Orchestrator Monitor Adapter for BEM but slot severity in event is not received
WARNING is the default severity value in the BMC Event Manager application. To resolve this issue, you must add a configuration parameter to the gateway.imcomm file.
To add the configuration parameter
1. Access the computer on which BMC Event Manager is installed and navigate to the $MCELL_HOME/etc directory. 2. Open the gateway.imcomm file and then add the following line:
cond=always
3. Restart the BMC Event Manager service.
BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation
The BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation consists of an actor adapter only. The actor adapter sends commands or requests to and receive responses from BMC BladeLogic Network Automation. In other words, the application adapter automates a majority of processes for BMC BladeLogic Network Automation. The BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation manipulates the configuration and compliance of network assets. The actor adapter for BMC BladeLogic Network Automation application uses the web-service APIs exposed by BMC BladeLogic Network Automation. The actor adapter enables you to perform the following categories of operations in BMC BladeLogic Network Automation:
361
basic operations, such as retrieve device information and device configuration basic jobs, such as backups, commits, job approvals, custom actions, and logging events This set of topics provides information about: Supported versions of BMC BladeLogic Network Automation Configuring the BMC BladeLogic Network Automation adapter BMC BladeLogic Network Automation application adapter module Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation
Supported versions of BMC BladeLogic Network Automation

The adapter supports versions 5.2, 5.3, 5.4, 8.1, and 8.1.01 of BMC BladeLogic Network Automation.
Configuring the BMC BladeLogic Network Automation adapter

You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the BMC BCAN product application. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view, and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration. Note The BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation contains an actor adapter only; it does not include a monitor adapter. The default name for the actor adapter is BCANActor.
To configure the adapter

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. Access the adapters page by clicking the Manage tab; then click the Adapters tab. 3. In the Adapters in Repository list, select the bmc-adapter-bmc-bladelogic-network-automation-actor versionNumber check box. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or skip to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements indicated with an asterisk (*). 7. ( optional ) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements and attributes from the adapter user guide into the Properties text
362
BMC Atrium Orchestrator Application Adapters 20.11.02 d. box, and then click OK. Note If the default value for an optional element is acceptable, omit the element. Do not include empty elements. e. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the configuration elements for the actor adapter. Node elements required to configure the actor adapter UI label Soap Url Element <soap-url> Definition Required
Specifies the URL for the remote SOAP service Conditional; required if The <soap-url> element has the following not specified in formats: the request For insecure communication: <soap-url>http:// IPAddress : portNumber </soap-url> For secure communication: <soap-url>https:// hostName : portNumber </soap-url> where,
IPAddress is the IP address of the computer where the application server is installed. hostName is the name of the computer where the application server is installed. portNumber specifies the port on which the application server is running, even if it is the default (otherwise, the adapter fails to install the certificate and adapter requests fail). Default value (for secure communication): 443 User Name <user-name> Specifies the user name for the BMC BladeLogic Network Automation server authentication Conditional; required if not specified in the request Conditional; required if not specified in the request
Password
<password>
Specifies the password for the user name specified
363
Soap Version
<soap-version>
Specifies the SOAP version to use Valid values: 1.1 (default), 1.21
Conditional; required if not specified in the request No
Use ssl certificate
<use-ssl-certificate>
Specifies whether to use an SSL certificate to establish a secure connection Set the value of this element to true when <soap-url> uses HTTPS. Set the value of this element to false or leave it blank when <soap-url> uses HTTP. Valid values: true, false (default)
Install Certificate
Specifies whether to install security certificates automatically Note: You do not need this element if <use-ssl-certificate> is false or blank. Set the value of this element to true if you prefer to have security certificates installed automatically (common). Set the value of this element to false if you prefer to manually export the security certificate from the BMC BladeLogic Network Automation server and manually import it into the BMC Atrium Orchestrator's local peer's cacerts file (rare). Valid values: true, false (default)
No
Allow Unsigned Certificate
<allow-unsigned-certificate Specifies whether to allow unsigned certificates from trusted zones > Valid values: true, false (default) Commonly, set the value of this element to true if you are using self-signed SSL certificates. Rarely, on ecommerce sites or military installations, if you need to use signed certificates such as Verisign or Thawte, set the value of this element to false.
No
364
Specifies the password to the keystore file (cacerts) local to the BMC Atrium Orchestrator peer Default value: changeit
No
Warning The value of the <passphrase> element is the passphrase for the cacerts certificate stored on the BMC Atrium Orchestrator local peer (CDP or AP) and not the BMC BladeLogic Network Automation target host. Changing the passphrase can be tricky and might destroy the cacerts security file integrity.
Verify the cacerts passphrase using the following command in UNIX or Linux: $ /opt/bmc/ao/cdp/jvm/bin/keytool -list -keystore /opt/bmc/ao/cdp/jvm/lib/security/cacerts
The following figure shows an XML sample to configure the adapter for insecure communication. XML sample to configure the actor adapter for insecure communication
<config> <soap-url>http://10.10.75.126:8480</soap-url> <user-name>sysadmin</user-name> <password>abc123</password> <soap-version>1.1</soap-version> </config>
The following figure shows an XML sample to configure the adapter for secure communication. XML sample to configure the adapter for secure communication
365
<config> <soap-url>https://s-17157:9443</soap-url> <user-name>sysadmin</user-name> <password>admin</password> <soap-version>1.1</soap-version> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>true</allow-unsigned-certificate> <passphrase>changeit</passphrase> </config>
BMC BladeLogic Network Automation application adapter module

Top-level processes for the BMC BladeLogic Network Automation adapter

The top-level processes perform high-level functions and call specialized processes in the subdirectories of the v5.2, v5.3, and v5.4 version directories. The top-level processes in the Project Explorer window execute the following version-specific BMC BladeLogic Network Automation processes: Create Items Find Items Update Items Perform Operations The following table lists the functional processes available for the top-level processes. Functional processes in the top-level processes Top-level process Create Items Find Items Find Items Find Items Find Items Find Items Functional process Add Substitution Parameter Get Configuration Get Devices Get Span Action Results Get Job Approval Types Retrieve Job Status by JobID Item type addSubstitutionParameter getConfiguration getDevices getSpanActionResults getJobApprovalTypes retrieveJobStatusByJobID Compatible with version 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.4, 8.1, 8.1.01
366
Find Items Find Items Find Items Find Items Find Items Find Items Find Items Find Items Update Items Update Items Update Items Update Items Update Items Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations
Get Simple Groups Get Substitution Parameter By Name Get Template Group By Name Get All Predefined Job Names Get Predefined Job Names Get Predefined Job Parameter Types Get All Shared Runtime Parameters Get All Firewall Rules Modify Substitution Parameter Modify Substitution Parameter Modify Template Group Modify Template Group Overwrite Firewall Rules Approve by Change ID Perform External Approval Login Logout Perform Backup Perform Custom Action Mark as Trusted by Config Date Merge by Config Type Merge Compliant All Assigned Send Job Summary Report Email
getSimpleGroups
5.2, 5.3, 5.4, 8.1, 8.1.01
getSubstitutionParameterByName 5.2, 5.3, 5.4, 8.1, 8.1.01 getTemplateGroupByName getAllPredefinedJobNames getPredefinedJobNames 5.2, 5.3, 5.4, 8.1, 8.1.01 5.3, 5.4, 8.1, 8.1.01 5.3, 5.4, 8.1, 8.1.01
getPredefinedJobParameterTypes 5.3, 5.4, 8.1, 8.1.01 getAllSharedRuntimeParameters getAllFirewallRules modifySubstitutionParameter modifySubstitutionParameter modifyTemplateGroup modifyTemplateGroup overwriteFirewallRules approveByChangeID performExternalApproval login logout performBackup performCustomAction markAsTrustedByConfigDate mergeByConfigType mergeCompliantAllAssigned sendJobSummaryReportEmail 5.4, 8.1, 8.1.01 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01
367
Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations Perform Operations
Log Critical Event Log Info Event Log Major Event Log Minor Event Log Warning Event Commit Restore by Template Group Merge by Adhoc Template Merge by Template Group Merge Compliant by Rule Merge Compliant by Rule Set Validate Predefined Job Parameters Submit Job
logCriticalEvent logInfoEvent logMajorEvent logMinorEvent logWarningEvent commit restoreByTemplateGroup mergeByAdhocTemplate mergeByTemplateGroup mergeCompliantByRule mergeCompliantByRuleSet
5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01 5.2, 5.3, 5.4, 8.1, 8.1.01
validatePredefinedJobParameters 5.3, 5.4, 8.1, 8.1.01 submitJob 5.3, 5.4, 8.1, 8.1.01
Setup Validation directory for the BMC BladeLogic Network Automation adapter
The processes in the Setup_Validation directory contain sample values for request elements. You can change these sample values quickly to reflect the values in your environment. A process is provided to test each supported method of executing operations in BMC BladeLogic Network Automation.
Utilities directory for the BMC BladeLogic Network Automation adapter

The Utilities directory contains helper and constructor processes. The functional processes require complex XML inputs. You can generate these complex XML inputs using the constructor processes in the Utilities directory.
Version directories for the BMC BladeLogic Network Automation adapter

The v5.2, v5.3, and v5.4 directories contain functional processes specific to a version of BMC BladeLogic Network Automation. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of the operation. In the v5.2 directory, the functional processes are grouped as follows: Authentication
368
Device_Information Events Jobs Reports In the v5.3 directory, the functional processes are grouped as Devices and Predefined_Jobs. In the v5.4 directory, the functional processes are grouped as Predefined_Jobs. The following table shows the compatibility of processes in version-specific directories with BMC BladeLogic Network Automation. Compatibility of processes in version-specific directories with BMC BladeLogic Network Automation VersionNumber Are processes directory in the versionNumber directory compatible with BMC BladeLogic Network Automation version 5.2? v5.2 v5.3 v5.4 Yes No No Are processes in the versionNumber directory compatible with BMC BladeLogic Network Automation version 5.3? Yes Yes No Are processes in the versionNumber directory compatible with BMC BladeLogic Network Automation version 5.4? Yes Yes Yes Are processes in the versionNumber directory compatible with BMC BladeLogic Network Automation version 8.1? Yes Yes Yes Are processes in the versionNumber directory compatible with BMC BladeLogic Network Automation version 8.1.01? Yes Yes Yes
Process inputs for the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation module
The following table describes the input elements used by a process in the adapter module. Process input elements Inputs <adapter name> <items> <connection parameters> Definition Specifies the name of the adapter that handles the request Contains the <item> XML elements used to execute the process Contains the elements needed for the adapter to connect to the target The <connection parameters> element contains the following elements: <soap-url> <user-name> <password> Required No Yes No
The following table describes the <connection parameters> elements used by a process in the adapter module.
369
<connection parameters> elements Element <soap-url> Definition Specifies the URL for the remote SOAP service The <soap-url> element has the following formats: For insecure communication: <soap-url>http:// IPAddress : portNumber </soap-url> For secure communication: <soap-url>https:// hostName : portNumber </soap-url> Required Conditional; required if not specified in the request
IPAddress is the IP address of the computer where the application server is installed. hostName is the name of the computer where the application server is installed. portNumber specifies the port on which the application server is running, even if it is the default (otherwise, the adapter fails to install the certificate and adapter requests fail). Default value (for secure communication): 443 <user-name> Specifies the user name for the BMC BladeLogic Network Automation server authentication Conditional; required if not specified in the request Conditional; required if not specified in the request Conditional; required if not specified in the request
<password>
Specifies the password for the user name specified
<soap-version> Specifies the SOAP version to use Valid values: 1.1 (default), 1.21
The following figure shows an XML sample for specifying <connection parameters> at run time. XML sample for specifying <connection parameters> at run time
<connection-parameters> <soap-version>1.1</soap-version> <soap-url>https://s-17157:9443</soap-url> <username>sysadmin</username> <password>bmcadmin</password> </connection-parameters>
Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation
You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity.
370
You do not need to specify configuration parameters in the actor adapter requests unless you want to override the adapter configuration. The following topics provide information about the types and the operations available with the adapter:
Authentication Service operations Device Service operations Report Service operation Job Service operations Span Action Service operations Events service operations Substitution Parameter Service operations Template Group Service operations Job Approval Type Service operations Group Service operation Predefined Jobs operation Firewall Service operations
Authentication Service operations

The following topics illustrates the adapter requests and responses for the following Authentication Service operations: Request and response for the Login operation Request and response for the Logout operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Login operation

The Login operation enables you to establish a session with the BMC BladeLogic Network Automation application using the specified user name and password. The following table describes the elements for the <items> XML element and adapter request for the Login operation.
Elements for the < items > XML element and adapter request for the Login operation
Element <entity>
Definition Specifies the type of operation: authentication
Required Yes Yes Yes
<operation-name> Specifies the name of operation: do-login <user-name> Specifies the user name for logging on to the BMC BladeLogic Network Automation application The user can be a system administrator, manager, planner, or viewer. <password> Specifies the password corresponding to the specified <user-name>
Yes
The following figure shows a sample <items> XML element for the Login operation. < items > XML element for the Login operation
371
<items> <item> <parameters> <user-name></user-name> <password></password> </parameters> </item> </items>
The following figure shows a sample adapter request for the Login operation. Sample adapter request for the Login operation
<bmc-configuration-automation-networks-request> <entity>authentication</entity> <request> <operation-name>do-login</operation-name> <parameters> <user-name>sysadmin</user-name> <password>bmc123</password> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Login operation. Adapter response for the Login operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>3892526615668584829</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Logout operation

The Logout operation enables you to close the web service session and log out from BMC BladeLogic Network Automation. The following table describes the elements for the <items> XML element and adapter request for the Logout operation.
Elements for the < items > XML element and adapter request for the Logout operation Element Definition Required
372
<entity>
Specifies the type of operation: authentication
Yes Yes Yes
<operation-name> Specifies the name of operation: do-logout <user-token> Specifies the session token returned during the execution of the Login operation
The following figure shows a sample <items> XML element for the Logout operation. < items > XML element for the Logout operation
<items> <item> <parameters> <user-token>-6800902384833057908</user-token> </parameters> </item> </items>
The following figure shows a sample adapter request for the Logout operation. Sample adapter request for the Logout operation
<bmc-configuration-automation-networks-request> <entity>authentication</entity> <request> <operation-name>do-logout</operation-name> <parameters> <user-token>-6800902384833057908</user-token> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the response for the sample Logout operation. Adapter response for the Logout operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>true</output> </parameters> </bmc-configuration-automation-networks-response>
The response parameter has a Boolean value of either: true: The user is successfully logged out.
373
false: The logout operation cannot be completed because the user is not logged in.
Device Service operations

The following topics illustrates the adapter requests and responses for the Device Service operations: Request and response for the Get Devices operation Request and response for the Get Configuration operation Request and response for the Add Device operation Request and response for the Delete Device operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Get Devices operation

The Get Devices operation enables you to retrieve a list containing detailed information about devices corresponding to the filtering criteria. The following table describes the elements for the <items> XML element and adapter request for the Get Devices operation.
Elements for the < items > XML element and adapter request for the Get Devices operation Element <device-filter> Definition Contains all of the individual elements that compose the filtering criteria for the operation Note: The <device-filter> element is required, but none of the following child elements is required. <dynamic-field-range> Specifies the filtering components using dynamic fields For example, Device inventory, Jobs, and Rule Sets Specifies the key string of a dynamic field Specifies the key string used to refer to a device Encloses a dynamic field as a collection of names and values Specifies a value assigned to a mode; see Access-mode constants Specifies the filtering components for retrieving devices based on device address Specifies device creation details, such as end date, start date, and time-period-type-id No Required Yes
<dynamic-field-key-string> <key> <dynamic-fields> <access-mode> <address-match>
No No No No No
<created>
No
374
<end-date>
Specifies the filtering components for retrieving devices based on the end date of a device Specifies the filtering components for retrieving devices based on the start date of a device Specifies the filtering components for retrieving devices based on the time period of a device
No
<start-date>
No
<time-period-type-id>
No
<device-agent-info-name>
Specifies the filtering components for No retrieving devices based on the configured device agent A device agent is deployed on one or more devices, allowing the devices to be managed remotely.
<device-security-profile-name> <device-type-id> <group-name> <ios-hw-filter>
Specifies the name of a device security profile Specifies a value assigned to a device type; see device type IDs Specifies the name of a group that contains the devices to be retrieved Locates a hardware entity For each backup, the BMC BladeLogic Network Automation application discovers hardware entities (for example, boards) and their associated attributes (for example, name, description, product identifier [PID], version identifier [VID], and serial number [SN]). The system discovers the total used, free, and flash memory. The device filter discovers hardware inventory that can be searched for using any hardware attribute.
No No No No
<last-span-action-days> <last-span-action-days-action-type> <last-span-action-days-flag> <last-span-action-error-match> <last-span-action-status> <last-span-action-status-action-type>
Specifies the last span action performed on the devices to be retrieved Specifies the last span action type for the devices to be retrieved Specifies the last span action flag for the devices to be retrieved Specifies the last span action error that the retrieved devices must match Specifies the last span action's status for the devices to be retrieved Specifies the action type of the last span action's status for the devices to be retrieved
No No No No No No
375
<last-span-action-status-flag>
Specifies whether to retrieve devices No based on the last span action status action No
<last-span-action-success-date-action-type> Specifies the last span action's success date action type for the devices to be retrieved <last-span-action-success-date-flag> <last-span-action-success-days> Specifies the last span action's success date flag for the devices to be retrieved Specifies that the span action was successful for the devices to be retrieved
No No No
<last-span-action-success-days-action-type> Specifies the last span action's success days action type for the devices to be retrieved <last-span-action-success-days-flag> <last-span-action-success-time-period> <model-match> <name-match> <no-discrepancies-flag> <no-discrepancies-include> <no-violations-flag> <no-violations-include> <online> Specifies the last span action's success days flag for the devices to be retrieved Specifies the last span action's success time period for the devices to be retrieved Specifies the model name Specifies the name of the device passed to retrieve device information Sorts the list of devices based on discrepancies flag Sorts the list of devices based on no-discrepancies flag Sorts the list of devices based on no-violations flag Sorts the list of devices based on no-violations-include flag Sorts the list of devices based on their online or offline status; see online constants Sorts the list of devices based on os-image-discrepancy flag Filters the list of devices based on os-image-discrepancy-include flag Filters the list of devices based on os-image name match Specifies the name of the realm to filter the device list Filters the list of devices based on running and startup discrepancy flag Filters the list of devices based on running and startup discrepancy include flag Filters the list of devices based on running trusted discrepancy flag
No No No No No No No No No
<os-image-discrepancy-flag> <os-image-discrepancy-include> <os-image-match> <realm-name> <running-startup-discrepancy-flag> <running-startup-discrepancy-include> <running-trusted-discrepancy-flag>
No No No No No No No
376
<running-trusted-discrepancy-include> <running-violation-flag> <running-violation-include> <startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include> <startup-violation-flag> <startup-violation-include> <transfer-mode> <vendor-id>
Filters the list of devices based on running trusted discrepancy include flag Filters the list of devices based on running violation flag Filters the list of devices based on running violation include Filters the list of devices based on startup trusted discrepancy flag Filters the list of devices based on startup trusted discrepancy include Filters the list of devices based on the startup violation flag Filters the list of devices based on the startup violation include Specifies a value assigned to a transfer mode; see transfer mode constants Specifies a value that identifies a vendor; see vendor IDs
No No No No No No No No
The following table lists the access-mode constants.
Access-mode constants Access-mode ACCESS_MODE_AUTO ACCESS_MODE_HTTP10 ACCESS_MODE_HTTP11 Constant 0 7 6
ACCESS_MODE_HTTPS10 5 ACCESS_MODE_HTTPS11 4 ACCESS_MODE_NULL ACCESS_MODE_SSH1 ACCESS_MODE_SSH2 ACCESS_MODE_TELNET -1 2 3 1
DEFAULT_ACCESS_MODE 0 The following table lists the devices and their supported IDs.
Devices and their supported IDs
377
Device 3Com SuperStack 3 Switch 3Com SuperStack Switch Alcatel ESS/SR Alcatel OmniSwitch 6600/7700/7800/8800 Cisco ASA/PIXOS Cisco Catalyst 1900/2820 Cisco CatOS Switch Cisco Content Services Switch Cisco IOS Switch/Router Cisco MDS 9000 Cisco VPN 3000 Concentrator Series Dell PowerConnect Enterasys SmartSwitch Router Extreme Networks F5 BigIP Foundry EdgeIron Switch Foundry NetIron/BigIron/FastIron/ServerIron HP ProCurve 1600/2424/4000/8000 Switch HP ProCurve 25xx Switch
ID 31 15 19 24 4 25 1 26 0 33 22 29 12 11 30 10 20 8 9
HP ProCurve 2600/2600-PWR/2800/4100/6108 Switch 17 Juniper JunOS Kentrox ServicePoint Marconi Switch NetScreen Firewall Nokia Firewall Nortel BayRS Router Nortel BayStack 460/470/5510/5520 Nortel Passport 1000 Series Nortel Passport 8000 Series Pedestal UBS SonicWALL Firewall Vanguard Router The following table lists the online constants. 16 21 5 6 14 7 32 23 27 18 28 13
378
Online constants Name Constant
DO NOT FILTER ON ONLINE -1 FILTER BY OFFLINE FILTER BY ONLINE 1 0
The following table lists the transfer mode constants.
Transfer mode constants Transfer mode TRANSFER_MODE_AUTO TRANSFER_MODE_FTP TRANSFER_MODE_NULL TRANSFER_MODE_SCP TRANSFER_MODE_TFTP Constant 0 2 -1 3 1
TRANSFER_MODE_TUNNELED 4 The following table lists the vendors IDs.
Vendor IDs Vendor 3Com Alcatel Cisco Dell Enterasys Extreme F5 Foundry HP Juniper ID 11 14 1 17 8 7 18 6 5 12
379
Kentrox Marconi NetScreen Nokia Nortel Pedestal
15 2 3 10 4 13
SonicWALL 16 Vanguard 9
The following figure shows a sample <items> XML element for the Get Devices operation. < items > XML element for the Get Devices operation
<items> <item> <parameters> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215098375937</end-date> <start-date>1215098375937</start-date> <time-period-type-id>1</time-period-type-id>
380
</created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-security-profile-name>a</device-security-profile-name> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <key>a</key> <end-date>1215098375937</end-date> <start-date>1215098375937</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match>
381
<name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter>
382
The following figure shows a sample adapter request for the Get Devices operation. Sample adapter request for the Get Devices operation
<bmc-configuration-automation-networks-request> <entity>device</entity> <request> <operation-name>get-devices</operation-name> <device-filter> <vendor-id>1</vendor-id> </device-filter> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the response for the sample Get Devices operation. Adapter response for the sample Get Devices operation
383
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <dynamic-fields> <element> <name>DeviceType</name> <values> <element>Cisco IOS Switch/Router</element> </values> </element> <element> <name>Description</name> <values> <element></element> </values> </element> </dynamic-fields> <key>714294386-12</key> <name>router</name> <realm> <key>955703509-1</key> <name>Default</name> </realm> <access-mode>1</access-mode> <address>10.10.75.50</address> <agent-info-key>1892835679-1</agent-info-key> <created>1217526664843</created> <current-running-config-key>1754072615-20</current-running-config-key> <current-startup-config-key>1754072615-22</current-startup-config-key> <device-security-profile-name>dsp</device-security-profile-name> <device-type-id>0</device-type-id> <online>true</online> <transfer-mode>1</transfer-mode> <trusted-running-config-key>1754072615-20</trusted-running-config-key> <trusted-startup-config-key>1754072615-22</trusted-startup-config-key> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Get Configuration operation

The Get Configuration operation enables you to retrieve information about the device configuration for a specified configuration, based on the configuration key. The following table describes the elements for the <items> XML element and adapter request for the Get Configuration operation.
Adapter request elements for the Get Configuration operation
384
Element
Definition
Required Yes
<config-key> Specifies the key associated with the configuration of any device You can retrieve the key for a device by executing the Get Devices operation. The following figure shows a sample <items> XML element for the Get Configuration operation. < items > XML element for the Get Configuration operation
<items> <item> <parameters> <config-key></config-key> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Configuration operation. Sample adapter request for the Get Configuration operation
<bmc-configuration-automation-networks-request> <entity>device</entity> <request> <operation-name>get-configuration</operation-name> <parameters> <config-key>1754072615-20</config-key> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the response for the sample Get Configuration operation. Adapter response for the Get Configuration operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <contents>\x00a!\x00aversion 12.2\x00aservice timestamps debug uptime\x00aservice timestamps log uptime\x00ano service password-encryption\x00a!\x00ahostname 10.10.75.129\x00a!\x00aenable secret 5 $1$T9IG$gTXIu8T24AgGqIokWlXmi0\x00aenable password bmc123\x00a!\x00aip subnet-zero\x00ano ip routing\x00ano ip cef\x00a!\x00a!\x00a!\x00acall rsvp-sync\x00a!\x00a!\x00a!\x00a!\x00a!\x00a!\x00a!\x00a!\x00ainterface FastEthernet0/0\x00a ip address 10.10.75.50 255.255.255.0\x00a no ip
385
route-cache\x00a no ip mroute-cache\x00a duplex half\x00a no cdp enable\x00a!\x00ainterface Serial1/0\x00ano ip address\x00a no ip route-cache\x00a no ip mroute-cache\x00a shutdown\x00a serial restart-delay 0\x00a no cdp enable\x00a!\x00ainterface Serial1/1\x00a no ip address\x00a no ip route-cache\x00a no ip mroute-cache\x00a shutdown\x00a serial restart-delay 0\x00a no cdp enable\x00a!\x00ainterface Serial1/2\x00a no ip address\x00a no ip route-cache\x00a no ip mroute-cache\x00a shutdown\x00a serial restart-delay 0\x00a no cdp enable\x00a!\x00ainterface Serial1/3\x00a no ip address\x00a no ip route-cache\x00a no ip mroute-cache\x00a shutdown\x00a serial restart-delay 0\x00a no cdp enable\x00a!\x00ainterface ATM2/0\x00a no ip address\x00a no ip route-cache\x00a no ip mroute-cache\x00a shutdown\x00a no atm ilmi-keepalive\x00a!\x00aip classless\x00ano ip http server\x00a!\x00alogging trap notifications\x00alogging 10.10.75.126\x00ano cdp run\x00asnmp-server community public RO\x00asnmp-server enable traps tty\x00a!\x00a!\x00adial-peer cor custom\x00a!\x00a!\x00a!\x00abanner motd \x003================================\x00a ================================\x00a WARNING: By accessing and using this\x00a computer system, you are consenting to\x00a system monitoring for network admin\x00a and security purposes.Unauthorized\x00a attempts to defeat or circumvent security\x00a features, to use the system for other\x00a than intended purposes, to deny service\x00a to authorized users, to access, obtain,\x00a alter, damage, or destroy information,\x00a or otherwise to interfere with the system\x00a or its operation is prohibited. Evidence\x00a of such acts may bedisclosed to law\x00a enforcement authorities and result\x00a in criminal prosecution under the Computer\x00a Fraud and Abuse Act of 1986 and the\x00a National Information Infrastructure\x00a Protection Act of 1996, codified at\x00a Section 1030 of Title 18 of the United\x00a States Code, or other applicable criminal laws.\x00a ================================================\x003\x00a!\x00aline con 0\x00aline aux 0\x00aline vty 0 4\x00a password bmc123\x00a login\x00a!\x00aend\x00a</contents> <key>1754072615-20</key> <change-i-d>mcr</change-i-d> <created>1217571052921</created> <historical>false</historical> <job-i-d>BCA000013</job-i-d> <trail>0</trail> <trusted>true</trusted><trusted-time>1218538926531</trusted-time>
386
</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Add Device operation

The Add Device operation enables you to add a device in the BMC BladeLogic Network Automation application using the configuration information passed in the adapter request. The following table describes the elements for the <items> XML element and adapter request for the Add Device operation.
Elements for the < items > XML element and adapter request for the Add Device operation Element <name> Definition Specifies the name of the device that you want to configure in the BMC BladeLogic Network Automation application Encloses either the name or the key of the realm A realm is a collection of devices. A device belongs to a single realm. <name> Specifies the name of the realm If no realms are set up, you must specify the default realm name, Default . <key> Specifies the key of the realm <category> <device-type-id> Conditional; required if <name> is absent Specifies the device category constrained by the device type Specifies a unique device type Yes Conditional; required if <key> is absent Required Yes
<realm>
Yes
Conditional: Not required if If y, you do not need this element. However, if <device-type-guid> is vendor-specific, you need this element. is device-specific Required if The <device-type-id> is available at the <device-type-guid> following location: installDir is vendor-specific \BCA-Networks-Data\DeviceTypeMap-custom Specifies the vendor-specific or device-specific Globally Unique identifier (GUID) Yes
<device-type-guid>
387
<online>
Places a device in online or offline mode Offline devices are: Not included in span actions (for example, Backup, Merge) Excluded from Reports Not present in device popup selectors Not included in Configuration Exports During a Device Import, you can select new devices to be placed in online or offline mode.
No
<external-id>
Specifies a unique identifier for the device obtained from an external system This element is used to synchronize the BMC BladeLogic Network Automation database with the BMC Atrium CMDB.
No
<primary- interface>
Specifies the primary interface (main path) to access the device Most of the span actions use the main or primary interface. Note: This element is supported by BMC BladeLogic Network Automation application v5.4 and later.
Yes
<auxilary-interface>
Specifies the auxiliary interface (secondary or No alternate path) to access the device The auxiliary interface allows you to access the following actions to assist in disaster recovery: backup merge commit reboot telnet or SSH session custom actions For example, normally, a device might be managed over the management LAN (primary interface). However, during an emergency, the console port (auxiliary interface) of the device might also be physically cabled to a terminal server. Note : This element is supported by BMC BladeLogic Network Automation application v5.4 and later.
388
<access-mode>
Specifies the protocol used by the device agent to log in to the device When you specify Auto , the device agent tries all the supported modes (for example, SSH2, SSH1, and Telnet) for the device, starting with the most secure mode, and then remembers the access mode that is successful for subsequent device interactions.
Yes
<address> <agent-info-name>
Specifies the device's IP address or host name Specifies the name of the device agent that manages the device If you do not have any remotely installed device agents, specify Local.
Yes Yes
<device-security-profile-name> Specifies the name of the Device Security Profile to be used as the device credentials If you do not configure any Device Security Profile, specify Auto. <transfer-mode> Specifies the protocol used by the device agent to transfer configuration files and OS images to and from the device When you select Auto, the device agent tries all the supported modes (for example, SCP, FTP, TFTP, and Tunneled) for the device, starting with the most secure mode, and then remembers the successful transfer mode for subsequent device interactions. <ena-nat-address> Specifies the Network Address Translation (NAT) used to access devices using TFTP, FTP, or SCP to transfer configuration and OS image files Note: This element is renamed to <nat-address> in BMC BladeLogic Network Automation v5.4 and later. <auto-dsp> Specifies a Boolean value that depends on the <device-security-profile-name> element If the <device-security-profile-name> element value is not Auto , set this element to true ; otherwise, else set this element value to false.
Yes
Yes
No
No
The following figure illustrates a sample <items> XML element for the Add Device operation for BMC BladeLogic Network Automation application v5.3. < items > XML element for the Add Device operation--v5.3
389
<items> <item> <parameters> <device-dto> <name></name> <realm> <name></name> <key></key> </realm> <access-mode></access-mode> <address></address> <agent-info-name></agent-info-name> <auto-dsp></auto-dsp> <category></category> <device-security-profile-name></device-security-profile-name> <device-type-guid></device-type-guid> <device-type-id></device-type-id> <ena-nat-address></ena-nat-address> <external-id></external-id> <online></online> <transfer-mode></transfer-mode> </device-dto> </parameters> </item> </items>
The following figure illustrates a sample <items> XML element for the Add Device operation for BMC BladeLogic Network Automation application v5.4 and later. < items > XML element for the Add Device operation--v5.4 and later
390
<items> <item> <parameters> <device-dto> <name></name> <realm> <name></name> </realm> <category></category> <device-type-id></device-type-id> <device-type-guid></device-type-guid> <online></online> <external-id></external-id> <primary-interface> <access-mode></access-mode> <address></address> <agent-info-name></agent-info-name> <device-security-profile-name></device-security-profile-name> <transfer-mode></transfer-mode> <nat-address></nat-address> <auto-dsp></auto-dsp> </primary-interface> <auxiliary-interface> <access-mode></access-mode> <address></address> <agent-info-name></agent-info-name> <device-security-profile-name></device-security-profile-name> <transfer-mode></transfer-mode> <nat-address></nat-address> <auto-dsp></auto-dsp> </auxiliary-interface> </device-dto> </parameters> </item> </items>
Note The <primary-interface> and <auxilary-interface> elements are supported by BMC BladeLogic Network Automation application v5.4 and later. Therefore, use these elements mentioned in the sample <items> XML with v5.4 and later of the BMC BladeLogic Network Automation application. In BMC BladeLogic Network Automation application v5.4 and later, the following elements are child elements of the <primary-interface> and <auxilary-interface> elements: <access-mode> <address> <agent-info-name> <device-security-profile-name> <transfer-mode> <nat-address> <auto-dsp>
391
The following figure shows a sample adapter request for the Add Device operation for BMC BladeLogic Network Automation application v5.3. Sample adapter request for the Add Device operation--v5.3
<bmc-configuration-automation-networks-request> <soap-version>1.1</soap-version> <entity>device</entity> <request> <operation-name>add-device</operation-name> <parameters> <device-dto> <name>TestNokiaCh112</name> <realm> <name>Realm2</name> </realm> <access-mode>1</access-mode> <address>10.128.248.26</address> <agent-info-name>test</agent-info-name> <category>98</category> <device-security-profile-name>testDsp</device-security-profile-name> <device-type-id>2007</device-type-id> <device-type-guid>334FDF46-59CA-006E-DE08-3496D4C27B5A</device-type-guid> <online>false</online> <transfer-mode>1</transfer-mode> <external-id>14574125412AB</external-id> <ena-nat-address>10.128.45.10</ena-nat-address> </device-dto> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows a sample adapter request for the Add Device operation for BMC BladeLogic Network Automation application v5.4 and later. Sample adapter request for the Add Device operation--v5.4 and later
392
<bmc-configuration-automation-networks-request> <soap-version>1.1</soap-version> <entity>device</entity> <request> <operation-name>add-device</operation-name> <parameters> <device-dto> <name>TestNokiaCh112</name> <realm> <name>Realm2</name> </realm> <category>98</category> <device-type-id>2007</device-type-id> <device-type-guid>334FDF46-59CA-006E-DE08-3496D4C27B5A</device-type-guid> <online>false</online> <external-id>14574125412AB</external-id> <primary-interface> <access-mode>1</access-mode> <address>10.128.248.26</address> <agent-info-name>test</agent-info-name> <device-security-profile-name>testDsp</device-security-profile-name> <transfer-mode>1</transfer-mode> <nat-address>10.128.45.10</nat-address> <auto-dsp>false</auto-dsp> </primary-interface> <auxiliary-interface> <access-mode>1</access-mode> <address>10.128.248.27</address> <agent-info-name>test1</agent-info-name> <device-security-profile-name>testDsp1</device-security-profile-name> <transfer-mode>1</transfer-mode> <nat-address>10.128.45.11</nat-address> <auto-dsp>false</auto-dsp> </auxiliary-interface> </device-dto> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the response for the sample Add Device operations. Adapter response for the Add Device operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>714294386-77</output> </parameters> </bmc-configuration-automation-networks-response>
393
The Add Device operation returns the device key as the value in the <output> element of the adapter response.
Request and response for the Delete Device operation

The Delete Device operation enables you to delete a device from the BMC BladeLogic Network Automation application. The <device-key> element is required in the <items> XML element to delete the device. The following figure shows a sample <items> XML element for the Delete Device operation. < items > XML element for the Delete Device operation
<items> <item> <parameters> <device-key></device-key> </parameters> </item> </items>
The following figure shows a sample adapter request for the Delete Device operation. Sample adapter request for the Delete Device operation
<bmc-configuration-automation-networks-request> <soap-version>1.1</soap-version> <entity>device</entity> <request> <operation-name>delete-device</operation-name> <parameters> <device-key>714294386-77</device-key> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the sample response for the Delete Device operation. Adapter response for the Delete Device operation
394
The Delete Device operation returns a Boolean value in the <output> element that indicates whether the device was deleted successfully from the system. The <output> value is true if the device was successfully deleted; otherwise, the value is false.
Report Service operation

The following topic illustrates the adapter request and response for the Report Service operation, Send Job Summary Report Email. Request and response for the Send Job Summary Report Email operation
Request and response for the Send Job Summary Report Email operation
The Send Job Summary Report Email operation sends a job summary report to one or more email recipients, based on the specified report parameters. The Job Summary report summarizes the span actions and configuration changes for a selected job. The following table describes the elements for the <items> XML element and adapter request for the Send Job Summary Report Email operation. Elements for the < items > XML element and adapter request for the Send Job Summary Report Email operation Element <change-id> Definition Specifies the Change ID when BMC Remedy IT Service Management integration is enabled If the integration is enabled, the Change ID field relates jobs to BMC Remedy Action Request System change requests. If the integration is disabled, the field representing this element is free-form, allowing users to use a two-level system to track change requests. Required Yes
395
<email-params>
Contains other elements that specify the details of the email message The <email-params> element contains the following child elements: <adhoc-addresses> <distribution-list-names> <user-names> <attachment-format> <attachment-included> <details-included> <link-included> <subject> Note: The <email-params> element is required, but none of its child elements is required.
Yes
<adhoc-addresses>
Lists the array of elements The report is sent to every email address present in <element> in the array of elements:
No
<adhoc-addresses>  <element>foo</element> <element>bar</element> </adhoc-addresses>
<distribution-list-names> Specifies the name of the distribution list created in the application <user-names> Contains an array of elements Each element in the array refers to the users that exist for a BMC BladeLogic Network Automation application. The report is sent to the email address of these users. <attachment-format> <attachment-included> <details-included> <link-included> <subject> <show-config-changes> <show-history> Specifies the attachment format to be included in the email message; see the Format constants table. Indicates whether to include the attachment in the email message Indicates whether to include the job details in the email message Indicates whether to include links in the email message Specifies the subject line for the email message Indicates whether to display the configuration changes in a report Indicates whether to include a history in the report
No No
No No No No No No No
The following table lists the format constants. Format constants
396
Format Excel format
Constant 1
HTML format 2 PDF format RTF format 3 4
The following figure shows a sample <items> XML element for the Send Job Summary Report Email operation. < items > XML element for the Send Job Summary Report Email operation
<items> <item> <parameters> <change-id></change-id> <email-params> <adhoc-addresses> <element>foo</element> <element>bar</element> </adhoc-addresses> <distribution-list-names> <element>foo</element> <element>bar</element> </distribution-list-names> <user-names> <element>foo</element> <element>bar</element> </user-names> <attachment-format>1</attachment-format> <attachment-included>true</attachment-included> <details-included>true</details-included> <link-included>true</link-included> <subject>a</subject> </email-params> <show-config-changes>true</show-config-changes> <show-history>true</show-history> </parameters> </item> </items>
The following figure shows a sample adapter request for the Send Job Summary Report Email operation. Sample adapter request for the Send Job Summary Report Email operation
397
<bmc-configuration-automation-networks-request> <entity>report</entity> <request> <operation-name>do-send-job-summary-report-email</operation-name> <parameters> <change-id>emailReq12</change-id> <email-params> <adhoc-addresses> <element>user1.ku@globallogic.com</element> </adhoc-addresses> <distribution-list-names> <element>List1</element> </distribution-list-names> <attachment-format>1</attachment-format> <attachment-included>true</attachment-included> <details-included>true</details-included> <link-included>true</link-included> <subject>From BCAN application</subject> </email-params> <show-config-changes>true</show-config-changes> <show-history>true</show-history> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Send Job Summary Report Email operation. Adapter response for the sample Send Job Summary Report Email operation
<adapter-response> <execution-duration>15859</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>true</output> </parameters> </bmc-configuration-automation-networks-response> </data> </adapter-response>
Job Service operations

The following topics illustrates the adapter requests and responses for the following Job Service operations: Request and response for the Job Approval or Job Rejection operation
398
Request and response for the Retrieve Job Status by JobID operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Job Approval or Job Rejection operation
The Job Approval or Job Rejection operation enables you to approve or reject a job that is submitted and is waiting for approval based on JobID, ChangeID, or TaskID. The following table details the available job operations.
Job operations Operation Approve by Job ID Approve by Change ID Approve by Task ID Description Approves a predefined job by the Job ID Approves a predefined job by the Change ID Approves a predefined job by the Task ID
Perform External Approval Approves a predefined job by the Job ID, Change ID, and Task ID
Note To approve a job, set the approve input parameter to true. To reject a job, set the approve parameter to false.
The following table describes the elements for the <items> XML element and adapter request for the Job Approval or Job Rejection operation.
Elements for the < items > XML element and adapter request for the Job Approval or Job Rejection operation Element <approve> Description Contains a Boolean value If the value is set to true, the waiting job is approved; if the value is set to false , the waiting job is rejected. <job-id> <change-id> <task-id> Specifies the job ID of the job for which approval is required that is waiting for approval Specifies the Change ID of the job for which approval is required that is waiting for approval Specifies the Task ID of the job for which approval is required that is waiting for approval Yes Yes Yes Required Yes
399
<annotation> Contains a description for the job
No
The following figure shows a sample <items> XML element for the Job Approval or Job Rejection operation. < items > XML element for the Job Approval or Job Rejection operation
 <items> <item> <parameters> <approve></approve> <job-id></job-id> <task-id></task-id> <annotation></annotation> </parameters> </item> </items>  <items> <item> <parameters> <approve>true</approve> <change-id>c11</change-id> <annotation>approve by change id</annotation> </parameters> </item> </items>  <items> <item> <parameters> <approve>true</approve> <task-id>t20</task-id> <annotation>approve by task id</annotation> </parameters> </item> </items>  <items> <item> <parameters> <approve>true</approve> <job-id>BCA000022</job-id> <change-id>c21</change-id> <task-id>t21</task-id> <annotation>external approval</annotation> </parameters> </item> </items>
The following figure shows a sample adapter request for the Job Approval or Job Rejection operation.
400
Sample adapter request for the Job Approval or Job Rejection operation
 <bmc-configuration-automation-networks-request> <entity>job</entity> <request> <operation-name>do-approval-by-jobid</operation-name> <parameters> <approve>true</approve> <job-id>BCA000041</job-id> <annotation>approve by job id</annotation> </parameters> </request> </bmc-configuration-automation-networks-request>  <bmc-configuration-automation-networks-request> <entity>job</entity> <request> <operation-name>do-approval-by-changeid</operation-name> <parameters> <approve>true</approve> <change-id>change1</change-id> <annotation>approve by change id</annotation> </parameters> </request> </bmc-configuration-automation-networks-request>  <bmc-configuration-automation-networks-request> <entity>job</entity>
The following figure illustrates the adapter response for the sample Job Approval or Job Rejection operation. Adapter response for the sample Job Approval or Job Rejection operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>0</output> </parameters> </bmc-configuration-automation-networks-response>
The return value in the response (the value of the <output> element) can be: -1: Job not found 0: No job approved (because it was already approved or does not need approval) >1: Number of jobs approved (can be more than 1 if the Change ID or some other non-unique identifier is specified)
401
Request and response for the Retrieve Job Status by JobID operation
The Retrieve Job Status by JobID operation enables you to retrieve the job status of the job matching the given job ID. The following table describes the elements for the <items> XML element and adapter request for the Retrieve Job Status by JobID operation.
Elements for the < items > XML element and adapter request for the Retrieve Job Status by JobID operation Element Definition <job-id> Required
Specifies the job ID for which the job status is to be retrieved Yes
The following figure shows a sample <items> XML element for the Retrieve Job Status by JobID operation. <items> XML element for the Retrieve Job Status by JobID operation
<items> <item> <parameters> <job-id></job-id> </parameters> </item> </items>
The following figure shows a sample adapter request for the Retrieve Job Status by JobID operation. Sample adapter request for the Retrieve Job Status by JobID operation
<bmc-configuration-automation-networks-request> <entity>job</entity> <request> <operation-name>retrieve-job-status-by-jobid</operation-name> <parameters> <job-id>BCA000156</job-id> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Retrieve Job Status by JobID operation. Adapter response for the sample Retrieve Job Status by JobID operation
402
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <originator>sysadmin</originator> <annotation>the job is rejected</annotation> <status>5</status> <timestamp>1283174442000</timestamp> </output> </parameters> </bmc-configuration-automation-networks-response>
The following table shows the job status codes and their meaning.
Job status codes Job status code Description 1 2 3 4 5 6 7 8 9 10 11 12 13 Aborted In Progress Cancelled Cancelled not Approved Completed Completed With Warnings Completed With Errors Created Rejected Scheduled Wait For Approval Draft Invalid
Span Action Service operations

The following topics illustrates the adapter requests and responses for the following Span Action Service operations: Request and response for the Device Rollback or Merge By Config Type operation Request and response for the Merge Compliant All Assigned operation Request and response for the Merge Compliant By Rule operation Request and response for the Merge Compliant By Rule Set operation
403
Request and response for the Merge By Adhoc Template operation Request and response for the Merge By Template Group operation Request and response for the Perform Backup operation Request and response for the Perform Custom Action operation Request and response for the Commit operation Request and response for the Mark as Trusted by Config Date operation Request and response for Restore By Template Group operation Request and response for the Get Span Action Results operations
Request and response for the Device Rollback or Merge By Config Type operation
The Merge By Config Type operation enables you to roll back a device configuration to a previous configuration. The following table describes the elements for the <items> XML element and adapter request for the Merge By Config Type operation.
Elements for the <items> XML element and adapter request for the Merge By Config Type operation Element <job-params-dto> Definition Contains all of the individual elements that enable you to roll back a device configuration to a previous configuration The <job-params-dto> element contains the following child elements: <annotation> <change-id> <device-filter> <dynamic-fields> <job-approval-type-key> <login-password> <run-at-time> <span-keys> <task-id> Note: The <job-params-dto> element is required, but none of its child elements is required. <annotation> <change-id> <device-filter> <dynamic-fields> Specifies a short description for the job Specifies the ID for the requested job Specifies the filtering criteria to use to retrieve the devices; see elements for more information about the device-filter element Contains dynamic fields as a collection of names and values No No No No Required Yes
404
<job-approval-type-key> Provides the key of the job approver to approve a job To obtain the job-approver information, use the Get Job Approval Types operation. <login-user-name> <login-password> <privileged-user-name> <privileged-password> <run-at-time> <span-keys> Specifies the login user name of a device Specifies the password of a device Specifies the privileged username of a device Specifies the privileged password of a device Specifies the time, in milliseconds, at which you want the job to run Specifies an array of elements in the following format:
<span-keys>  <element>foo</element> <element>bar</element> </span-keys>
No
No
No Yes
If the span-key is for device or realms, you can use the <device-filter> element to filter the devices further. <task-id> <wait-for-completion> Defines a task ID that is unique to a job Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <config-type> <config-date> Specifies the configuration type to be merged or rolled back; see configuration types for details about config types Specifies the date of the configuration to be merged The date format is in milliseconds (for example, 1219838630562) <smart-merge-mode> <syntax-scan> <make-trusted> <commit> Specifies the mode of merge operation; see smart-merge-mode constants for more information about the smart-merge-mode Indicates whether a syntax scan must be done before the merging Indicates whether the merged configuration must be marked as trusted Indicates whether the configuration must be committed No No No No Yes Yes No No
The following table lists the configuration types supported for merge operations.
Configuration types supported for merge operations Configuration type Constant
405
CFG_TYPE_TRUSTED_RUNNING
CFG_TYPE_HISTORICAL_RUNNING 5 CFG_TYPE_TARGET 7
The following table lists the smart-merge-mode constants.
smart-merge-mode constants Mode SMART MERGE DISABLED Constant 0
SMART MERGE FOR SUPPORTED ONLY 1 SMART MERGE WITH REGULAR MERGE 2 The following figure shows a sample <items> XML element for the Merge By Config Type operation. <items> XML element for the Merge By Config Type operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields>
406
<key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag>
407
<last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancyflag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values>
408
</element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215099084593</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <config-type>1</config-type> <config-date>1215101512328</config-date> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>true</syntax-scan> <make-trusted>true</make-trusted> <commit>true</commit>
409
The following figure shows a sample adapter request for the Merge By Config Type operation. Sample adapter request for Merge By Config Type operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> operation-name>do-merge-by-config-type</operation-name> <parameters> <job-params-dto> <annotation>Merge by config type</annotation> <change-id>mcty01</change-id> <span-keys> <element>714294386-41</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <config-type>5</config-type> <config-date>1219068828250</config-date> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>false</syntax-scan> <make-trusted>true</make-trusted> <commit>true</commit> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Merge By Config Type operation. Adapter response for the sample Merge By Config Type operations
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>BCA000159</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Merge Compliant All Assigned operation
410
For enforced compliance, a configuration is enforced to comply to a standard. A standard is defined as a set of rules. Enforcement is requested to all assigned Rule Sets, a specific Rule Set, or a specific rule. Merge Compliant All Assigned operation enforces a configuration to comply to all assigned Rule Sets. The following table describes the elements for the <items> XML element and adapter request for the Merge Compliant All Assigned operation.
Elements for the <items> XML element and adapter request for the Merge Compliant All Assigned operation Element <job-params-dto> Definition Contains all of the individual elements that enforce a configuration to comply to all assigned Rule Sets; see elements for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <smart-merge-mode> <syntax-scan> <make-trusted> <commit> Specifies the mode of merge operation; see smart-merge-mode constants for more information about the smart-merge-mode Indicates whether the syntax needs a scan before the merge Indicates whether to mark the merged configuration as trusted Indicates whether to commit the configuration
No
No No No No
The following figure shows a sample <items> XML element for the Merge By Config Type operation. <items> XML element for the Merge Compliant All Assigned operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range>
411
<dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter>
412
<last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancyflag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values>
413
<element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215099084593</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>true</syntax-scan> <make-trusted>true</make-trusted> <commit>true</commit>
414
The following figure shows a sample adapter request for the Merge Compliant All Assigned operation. Sample adapter request for the Merge Compliant All Assigned operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-merge-compliant-all-assigned</operation-name> <parameters> <job-params-dto> <annotation>merge compliant all assigned</annotation> <change-id>mcaa02</change-id> <span-keys> <element>714294386-41</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <smart-merge-mode>0</smart-merge-mode> <syntax-scan>true</syntax-scan> <make-trusted>true</make-trusted> <commit>true</commit> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Merge Compliant All Assigned operation. Adapter response for the sample Merge Compliant All Assigned operation
Request and response for the Merge Compliant By Rule operation

The Merge Compliant By Rule operation enforces a configuration to comply to the rules specified by the rule key. The following table describes the elements for the <items> XML element and adapter request for the Merge Compliant By Rule operation.
415
Elements for the <items> XML element and adapter request for the Merge Compliant By Rule operation Element <job-params-dto> Definition Contains all of the individual elements that enforce a configuration to comply to all assigned Rule Sets; see elements for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <rule-key> <smart-merge-mode> <syntax-scan> <make-trusted> <commit> <reboot> Specifies the rule's key, against which the configuration must be compliant Specifies the mode of merge operation; see smart-merge-mode constants for more information Indicates whether to scan the syntax before the merge Indicates whether to mark the merged configuration as trusted Indicates whether to commit the configuration Indicates whether to reboot the device after merge
No
Yes No No No No No
The following figure shows a sample <items> XML element for Merge Compliant By Rule operation. <items> XML element for the Merge Compliant By Rule operation
<items> item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element>
416
<name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1217496607421</end-date> <start-date>1217496607421</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type>
417
<last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1217496607421</end-date> <start-date>1217496607421</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name>
418
<values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1217496607421</run-at-time> <span-keys> <element>foo</element> <element>bar</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <rule-key>a</rule-key> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>true</syntax-scan> <make-trusted>true</make-trusted> <commit>false</commit> <reboot>true</reboot>
419
The following figure shows a sample adapter request for the Merge Compliant By Rule operation. Sample adapter request for the Merge Compliant By Rule operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-merge-compliant-by-rule</operation-name> <parameters> <job-params-dto> <annotation>merge compliant by rule</annotation> <change-id>mr02</change-id> <span-keys> <element>714294386-12</element> </span-keys> </job-params-dto> <wait-for-completion>true</wait-for-completion> <rule-key>1744721856-3</rule-key> <smart-merge-mode>0</smart-merge-mode> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit> <reboot>false</reboot> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Merge Compliant By Rule operation. Adapter response for the sample Merge Compliant By Rule operation
Request and response for the Merge Compliant By Rule Set operation
The Merge Compliant By Rule Set operation enforces a configuration to comply to the rule set specified by the rule set key.
420
The following table describes the elements for the <items> XML element and adapter request for the Merge Compliant By Rule Set operation.
*Elements for the <items> XML element and adapter request for the Merge Compliant By Rule Set operation || Element || Definition || Required || <job-params-dto> Contains all of the individual elements that enforce a configuration to comply to the rule set specified by the rule set key; see elements for more information about the child elements of this element Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <rule-set-key> <smart-merge-mode> <syntax-scan> <make-trusted> <commit> <reboot> Specifies the rule's key, against which the configuration must be compliant Specifies the mode of merge operation; see smart-merge-mode constants for more information Indicates whether to scan the syntax before the merge Indicates whether to mark the merged configuration as trusted Indicates whether to commit the configuration Indicates whether to reboot the device after merge
No
Yes No No No No No
The following figure shows a sample <items> XML element for Merge Compliant By Rule Set operation. <items> XML element for the Merge Compliant By Rule Set operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range>
421
<dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1217496607421</end-date> <start-date>1217496607421</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter>
422
<last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1217496607421</end-date> <start-date>1217496607421</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values>
423
<element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1217496607421</run-at-time> <span-keys> <element>foo</element> <element>bar</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <rule-set-key>a</rule-set-key> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>true</syntax-scan> <make-trusted>true</make-trusted> <commit>false</commit> <reboot>true</reboot>
424
The following figure shows a sample adapter request for the Merge Compliant By Rule Set operation. Sample adapter request for the Merge Compliant By Rule Set operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-merge-compliant-by-rule-set</operation-name> <parameters> <job-params-dto> <annotation>merge compliant by rule set</annotation> <change-id>mrs02</change-id> <span-keys> <element>714294386-12</element> </span-keys> </job-params-dto> <wait-for-completion>true</wait-for-completion> <rule-set-key>888138471-1</rule-set-key> <smart-merge-mode>1</smart-merge-mode> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit> <reboot>false</reboot> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Merge Compliant By Rule Set operation. Adapter response for the sample Merge Compliant By Rule Set operation
Request and response for the Merge By Adhoc Template operation

The Merge By Adhoc Template operation creates a merge job with the given adhoc template and returns the job ID of the newly created job.
425
The following table describes the elements for the <items> XML element and adapter request for the Merge By Adhoc Template operation.
Elements for the <items> XML element and adapter request for the Merge By Adhoc Template operation Element <job-params-dto> Definition Contains all of the individual elements that create a merge job with the given adhoc template; see elements for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <adhoc-template> Specifies the data to be merged This element must not be null or empty. <syntax-scan> <make-trusted> <commit> <reboot> Indicates whether to scan the syntax before the merge Indicates whether to mark the merged configuration as trusted Indicates whether to commit the configuration Indicates whether to reboot the device after merge
No
Yes
No No No No
The following figure shows a sample <items> XML element for the Merge By Adhoc Template operation. <items> XML element for the Merge By Adhoc Template operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range>  <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element>
426
</dynamic-field-range> <dynamic-fields>  <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id>
427
</memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> 
428
<element> <name>a</name> <values>  <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values>  <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215502976937</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <adhoc-template>a</adhoc-template> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit>
429
The following figure shows a sample adapter request for the Merge By Adhoc Template operation. Sample adapter request for the Merge By Adhoc Template operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-merge-by-adhoc-template</operation-name> <parameters> <job-params-dto> <annotation>adhoc template merge</annotation> <change-id>ch122</change-id> <span-keys> <element>714294386-12</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <adhoc-template>logging on</adhoc-template> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Merge By Adhoc Template operation. Adapter response for the sample Merge By Adhoc Template operation
Request and response for the Merge By Template Group operation

The Merge By Template Group operation creates a merge job with the specified template group and returns the Job ID of the newly created job.
430
The following table describes the elements for the <items> XML element and adapter request for the Merge By Template Group operation.
Elements for the <items> XML element and adapter request for the Merge By Template Group operation Element <job-params-dto> Definition Contains all of the individual elements that create a merge job with the specified template group; see elements for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <template-group-key> Indicates the database key that decides the template group is to be merged The system selects the contents within the template group appropriate for each device. You can execute a Get Template Group By Name operation to retrieve template group information. <syntax-scan> <make-trusted> <commit> Indicates whether to scan the syntax before the merge Indicates whether to mark the merged configuration as trusted Indicates whether to commit the configuration
No
Yes
No No No No
<run-time-parameters> Specifies the runtime substitution parameters whose values will be used in the merged template group contents This element can be null when the template group does not use any runtime parameters. The following figure shows a sample <items> XML element for Merge By Template Group operation. < items > XML element for the Merge By Template Group operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range>  <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element>
431
<dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields>  <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key>
432
<max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields>
433
 <element> <name>a</name> <values>  <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values>  <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215502976937</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <template-group-key>a</template-group-key> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit> <runtime-parameters>  <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </runtime-parameters>
434
The following figure shows a sample adapter request for the Merge By Template Group operation. Sample adapter request for the Merge By Template Group operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-merge-by-template-group</operation-name> <parameters> <job-params-dto> <annotation>device backup</annotation> <change-id>ch133</change-id> <span-keys> <element>714294386-12</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <template-group-key>1034341772-1</template-group-key> <syntax-scan>false</syntax-scan> <make-trusted>false</make-trusted> <commit>false</commit> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Merge By Template Group operation. Adapter response for the sample Merge By Template Group operation
{<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>BCA000165</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Perform Backup operation

The Perform Backup operation executes a backup action on one or more devices based on the specified parameters. A backup action copies the running and startup configurations from the device to the database.
435
The following table describes the elements for the <items> XML element and adapter request for the Perform Backup operation.
Elements for the < items > XML element and adapter request for the Perform Backup operation Element <job-params-dto> Definition Required
Contains all of the individual elements that execute a backup action on Yes one or more device; see elements for more information about the child elements of this element No
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. The following figure shows a sample <items> XML element for the Perform Backup operation. < items > XML element for the Perform Backup operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields>
436
<key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag>
437
<last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values>
438
</element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215099084593</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion>
439
The following figure shows a sample adapter request for the Perform Backup operation. Sample adapter request for the Perform Backup operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-backup</operation-name> <parameters> <job-params-dto> <annotation>device backup</annotation> <change-id>ch1</change-id> <span-keys> <key-string>714294386-41</key-string> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Perform Backup operation. Adapter response for the sample Perform Backup operation
Request and response for the Perform Custom Action operation

Custom actions are scripts. BMC delivers a set of factory-installed custom actions. You can develop your own custom actions. Custom actions are commonly used to: Execute show commands to collect device information for reporting and analysis Get device information used by a subsequent Job Span action The following table describes the elements for the <items> XML element and adapter request for the Perform
440
Custom Action operation.
Elements for the < items > XML element and adapter request for the Perform Custom Action operation || Element || Definition || Required || <job-params-dto> Contains all of the individual elements that enable you to perform custom actions; see elements for more information about the child elements of this element Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <custom-action-dto> Specifies the name of the custom action; see custom-action-dto for more information about this element The {{<custom-action-dto>} element contains the following child elements: <annotation> <id> <key> <commit-flag> <make-trusted-flag> <reboot-flag> <runtime-props> <annotation> <id> Specifies a short description for the custom action Indicates the ID associated with a custom action Note: This element is renamed to <guid> in BMC BladeLogic Network Automation v5.3.01 and later. <key> <commit-flag> <make-trusted-flag> <reboot-flag> <runtime-props> Specifies the key for the custom action Indicates whether to commit the configuration Indicates whether to mark the configuration as trusted Indicates whether to reboot the device after performing the custom action vSpecifies a custom action with runtime properties, which is a collection of names and values
No
Yes
No Yes
No No No No No
The following table lists the custom action names and their IDs.
Custom action names and their IDs Custom action n ame Show Show Interface Rates ID 2002 2003
441
Set Local Password for CATOS Set Enable Password for CATOS
2004 2005
Set Localuser Password for CATOS 2006 Get System Serial Number Ping Remote Node Show Image Format Show VLANs Get Trunk Interfaces Show AUX Modem Status Show VTP Mode 2007 2008 2009 2010 2011 2012 2013
The following figure shows a sample <items> XML element for the Perform Custom Action operation. <items> XML element for the Perform Custom Action operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match>
442
<created> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days>
443
<last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key>
444
<login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215099084593</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <custom-action-dto> <annotation>a</annotation> <id>1</id> <key>a</key> <commit-flag>true</commit-flag> <make-trusted-flag>true</make-trusted-flag> <reboot-flag>true</reboot-flag> <runtime-props> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </runtime-props> </custom-action-dto>
445
The following figure shows a sample adapter request for the Perform Custom Action operation. Sample adapter request for the Perform Custom Action operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-custom-action</operation-name> <parameters> <job-params-dto> <annotation>custom action</annotation> <change-id>chng01</change-id> <span-keys> <element>714294386-41</element> </span-keys> </job-params-dto> <wait-for-completion>true</wait-for-completion> <custom-action-dto> <annotation>Show VTP Mode</annotation> <id>2013</id> <commit-flag>false</commit-flag> <make-trusted-flag>false</make-trusted-flag> <reboot-flag>false</reboot-flag> </custom-action-dto> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Perform Custom Action operation. Adapter response for the sample Perform Custom Action operation
{<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>BCA000157</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Commit operation

The Commit operation applies to devices supporting a startup configuration. The Commit operation copies the
446
running configuration of a device to the startup configuration (for example, write memory). The Commit operation ensures that the startup configuration matches the running configuration, if the device reboots. The following table describes the elements for the <items> XML element and adapter request for the Commit operation.
*Elements for the < items > XML element and adapter request for the Commit operation Element <job-params-dto> Definition Contains all of the individual elements that copy the running configuration of a device to the startup configuration; see elements for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <make-trusted> Indicates whether to mark the merged configuration as trusted
No
No
The following figure shows a sample <items> XML element for the Commit operation. <items> XML element for the Commit operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range>  <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields>  <element> <name>a</name> <value>a</value> </element>
447
<element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match>
448
<last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields>  <element> <name>a</name> <values>  <element>foo</element> <element>bar</element> </values>
449
</element> <element> <name>b</name> <values>  <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215502976937</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <make-trusted>true</make-trusted>
450
The following figure shows a sample adapter request for the Commit operation. Sample adapter request for the Commit operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-commit</operation-name> <parameters> <job-params-dto> <annotation>commit</annotation> <change-id>ch121</change-id> <span-keys> <element>714294386-12</element> <element>714294386-13</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <make-trusted>true</make-trusted> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Commit operation. Adapter response for the sample Commit operation
Request and response for the Mark as Trusted by Config Date operation
For configuration revision control, the Mark as Trusted by Config Date operation enables authorized users to designate for a device, the trusted (desired state), running and startup configurations. The following table describes the elements for the <items> XML element and adapter request for the Mark as Trusted by Config Date operation.
451
Elements for the < items > XML element and adapter request for the Mark as Trusted by Config Date operation Element <job-params-dto> Definition Contains all of the individual elements that copy the running configuration of a device to the startup configuration; see Request and response for the Device Rollback or Merge By Config Type operation for more information about the child elements of this element Required Yes
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <running-trail> Indicates whether the configuration being merged to the device is a running configuration The service retrieves the right configuration to merge, based on the date and the configuration trail specified. <startup-trail> Indicates whether the configuration being merged to the device is a startup configuration The service retrieves the right configuration to merge, based on the date and the configuration trail specified. <config-date> Specifies the configuration date, in milliseconds
No
No
No
Yes
The following figure shows a sample <items> XML element for the Mark as Trusted by Config Date operation. <items> XML element for the Mark as Trusted by Config Date operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range> <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields>
452
<element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match> <memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days>
453
<last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215099084593</end-date> <start-date>1215099084593</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include> <startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element>
454
<element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215099084593</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion>true</wait-for-completion> <running-trail>true</running-trail> <startup-trail>true</startup-trail> <config-date>1215100293375</config-date>
455
The following figure shows a sample adapter request for the Mark as Trusted by Config Date operation. Sample adapter request for the Mark as Trusted by Config Date operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-mark-as-trusted-by-config-date</operation-name> <parameters> <job-params-dto> <annotation>Do mark as trusted by config date</annotation> <change-id>ch03</change-id> <span-keys> <element>714294386-41</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <running-trail>true</running-trail> <startup-trail>true</startup-trail> <config-date>1219068828250</config-date> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Mark as Trusted by Config Date operation. Adapter response for the sample Mark as Trusted by Config Date operation
Request and response for Restore By Template Group operation

The Restore By Template Group operation creates a BMC BladeLogic Network Automation restore job with the given template group and returns the Job ID of the newly created job. The following table describes the elements for the <items> XML element and adapter request for the Restore By Template Group operation.
456
Elements for the <items> XML element and adapter request for the Restore By Template Group operation Element <job-params-dto> Definition Required
Contains all of the individual elements that create a BMC BladeLogic Yes Network Automation restore job with the given template group; see elements for more information about the child elements of this element No
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish. <template-group-key> Specifies the database key corresponding to the template group to be merged The system selects the contents within the template group appropriate for each device. You can execute a Get Template Group By Name operation to retrieve template group information. <make-trusted> Indicates whether to mark the merged configuration as trusted Indicates if the resulting configuration or configurations should be marked as trusted <reboot> Indicates whether to reboot the device after merge Indicates if the device or devices should be rebooted after the template group is restored <run-time-parameters> Specifies the runtime substitution parameters whose values will be used in the merged template group contents This element can be null when the template group does not use any runtime parameters.
Yes
No
No
No
The following figure shows a sample <items> XML element for the Restore By Template Group operation. <items> XML element for the Restore By Template Group operation
<items> <item> <parameters> <job-params-dto> <annotation>a</annotation> <change-id>a</change-id> <device-filter> <dynamic-field-range>  <element> <dynamic-field-key-string>a</dynamic-field-key-string> <range> <key>a</key> </range>
457
</element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields>  <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <access-mode>1</access-mode> <address-match>a</address-match> <created> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </created> <device-agent-info-name>a</device-agent-info-name> <device-security-profile-name>a</device-security-profile-name> <device-type-id>1</device-type-id> <group-name>a</group-name> <ios-hw-filter> <entity-descr-match>a</entity-descr-match> <entity-name-match>a</entity-name-match> <entity-pid-match>a</entity-pid-match> <entity-sn-match>a</entity-sn-match> <entity-vid-match>a</entity-vid-match> <file-system-free-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-free-size> <file-system-name-match>a</file-system-name-match> <file-system-total-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </file-system-total-size> <memory-name-match>a</memory-name-match>
458
<memory-size> <key>a</key> <max>1</max> <max-inclusive>true</max-inclusive> <min>1</min> <min-inclusive>true</min-inclusive> <range-type-id>1</range-type-id> </memory-size> </ios-hw-filter> <last-span-action-days>1</last-span-action-days> <last-span-action-days-action-type>1</last-span-action-days-action-type> <last-span-action-days-flag>true</last-span-action-days-flag> <last-span-action-error-match>a</last-span-action-error-match> <last-span-action-status>1</last-span-action-status> <last-span-action-status-action-type>1</last-span-action-status-action-type> <last-span-action-status-flag>true</last-span-action-status-flag> <last-span-action-success-date-action-type>1</last-span-action-success-date-action-type> <last-span-action-success-date-flag>true</last-span-action-success-date-flag> <last-span-action-success-days>1</last-span-action-success-days> <last-span-action-success-days-action-type>1</last-span-action-success-days-action-type> <last-span-action-success-days-flag>true</last-span-action-success-days-flag> <last-span-action-success-time-period> <key>a</key> <end-date>1215502976937</end-date> <start-date>1215502976937</start-date> <time-period-type-id>1</time-period-type-id> </last-span-action-success-time-period> <model-match>a</model-match> <name-match>a</name-match> <no-discrepancies-flag>true</no-discrepancies-flag> <no-discrepancies-include>true</no-discrepancies-include> <no-violations-flag>true</no-violations-flag> <no-violations-include>true</no-violations-include> <online>1</online> <os-image-discrepancy-flag>true</os-image-discrepancy-flag> <os-image-discrepancy-include>true</os-image-discrepancy-include> <os-image-match>a</os-image-match> <realm-name>a</realm-name> <running-startup-discrepancy-flag>true</running-startup-discrepancy-flag> <running-startup-discrepancy-include>true</running-startup-discrepancy-include> <running-trusted-discrepancy-flag>true</running-trusted-discrepancy-flag> <running-trusted-discrepancy-include>true</running-trusted-discrepancy-include> <running-violation-flag>true</running-violation-flag> <running-violation-include>true</running-violation-include> <startup-trusted-discrepancy-flag>true</startup-trusted-discrepancy-flag> <startup-trusted-discrepancy-include>true</startup-trusted-discrepancy-include>
459
<startup-violation-flag>true</startup-violation-flag> <startup-violation-include>true</startup-violation-include> <transfer-mode>1</transfer-mode> <vendor-id>1</vendor-id> </device-filter> <dynamic-fields>  <element> <name>a</name> <values>  <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values>  <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <job-approval-type-key>a</job-approval-type-key> <login-password>a</login-password> <login-user-name>a</login-user-name> <privileged-password>a</privileged-password> <privileged-user-name>a</privileged-user-name> <run-at-time>1215502976937</run-at-time> <span-keys> <element>a</element> <element>b</element> </span-keys> <task-id>a</task-id> </job-params-dto> <wait-for-completion></wait-for-completion> <template-group-key>1034341772-1</template-group-key> <make-trusted>false</make-trusted> <reboot>false</reboot> <runtime-parameters>  <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </runtime-parameters>
460
The following figure shows a sample adapter request for the Restore By Template Group operation. Sample adapter request for the Restore By Template Group operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>do-restore-by-template-group</operation-name> <parameters> <job-params-dto> <annotation>Restore by template group</annotation> <change-id>ch341</change-id> <span-keys> <element>714294386-12</element> </span-keys> </job-params-dto> <wait-for-completion>false</wait-for-completion> <template-group-key>1034341772-1</template-group-key> <make-trusted>true</make-trusted> <reboot>false</reboot> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Restore By Template Group operation. Adapter response for the sample Restore By Template Group operation
Request and response for the Get Span Action Results operations
The Get Span Action Results operation returns the span action results of the job that matches the specified Job ID. The span action results are available only after the job status is completed. The Get Span Action Results operation does not work if the status of a job is one of the following: Draft
461
Waiting for approval Rejected The following table describes the elements for the <items> XML element and adapter request for the Get Span Action Results operation.
Elements for the <items> XML element and adapter request for the Get Span Action Results operation Element Definition Required
<job-id> Specifies the unique job ID for the required job Yes
This element cannot be null or empty.
The following figure shows a sample <items> XML element for the Get Span Action Results operation. <items> XML element for the Get Span Action Results operation
<items> <item> <parameters> <job-id></job-id> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Span Action Results operation. Sample adapter request for the Get Span Action Results operation
<bmc-configuration-automation-networks-request> <entity>span-action</entity> <request> <operation-name>get-span-action-results</operation-name> <parameters> <job-id>BCA000166</job-id> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get Span Action Results operation. Adapter response for the sample Get Span Action Results operation
462
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <end-time>1219248444953</end-time> <start-time>1219248416796</start-time> <status>1</status> <results> <element> <end-time>1219248444921</end-time> <error-message>None.</error-message> <key>1515263327-176</key> <name>cisco4003-01</name> <start-time>1219248416828</start-time> <status>1</status> </element> </results> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
Events service operations

This topic illustrates the adapter request and response for the Events service operation, Log Events. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Log Events operation

The adapter can log an event into the system with a severity of Critical, Major, Minor, Warning, or Info. The types of Log Event operations supported by the adapter are: LogCriticalEvent LogInfoEvent LogMajorEvent LogMinorEvent LogWarningEvent The following table describes the elements for the <items> XML element and adapter request for the Log Events operation.
Elements for the <items> XML element and adapter request for the Log Events operation Element Definition Required
463
<event-description> Describes the event to be logged <target> <target-key> Specifies the target for which the event is logged Specifies the key of the target The element meter and its key string must not be null.
Yes Yes Yes
The following figure shows a sample <items> XML element for the Log Events operation. <items> XML element for the Log Events operation
<items> <item> <parameters> <event-description>a</event-description> <target>a</target> <target-key>a</target-key> </parameters> </item> </items>
The following figure shows a sample adapter request for the Log Events operation. Sample adapter request for the Log Events operation
 <bmc-configuration-automation-networks-request> <entity>event</entity> <request> <operation-name>do-log-critical-event</operation-name> <parameters> <event-description>Log critical event </event-description> <target>router</target> <target-key>714294386-12</target-key> </parameters> </request> </bmc-configuration-automation-networks-request>  <bmc-configuration-automation-networks-request> <entity>event</entity> <request> <operation-name>do-log-info-event</operation-name> <parameters> <event-description>Log Info event </event-description> <target>router</target> <target-key>714294386-12</target-key> </parameters> </request> </bmc-configuration-automation-networks-request>
464
 <bmc-configuration-automation-networks-request> <entity>event</entity> <request> <operation-name>do-log-major-event</operation-name> <parameters> <event-description>Log Major event </event-description> <target>router</target> <target-key>714294386-12</target-key> </parameters> </request> </bmc-configuration-automation-networks-request>  <bmc-configuration-automation-networks-request> <entity>event</entity> <request> <operation-name>do-log-minor-event</operation-name> <parameters> <event-description>Log Minor event </event-description> <target>router</target> <target-key>714294386-12</target-key> </parameters> </request> </bmc-configuration-automation-networks-request>  <bmc-configuration-automation-networks-request> <entity>event</entity> <request> <operation-name>do-log-warning-event</operation-name> <parameters> <event-description>Log Warning event </event-description> <target>router</target> <target-key>714294386-12</target-key>
465
</parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Log Events operation. Adapter response for the sample Log Events operation
Substitution Parameter Service operations

The following topics illustrates the adapter requests and responses for the following Substitution Parameter Service operations: Request and response for the Add Substitution Parameter operation Request and response for the Modify Substitution Parameter operation Request and response for the Get Substitution Parameter by Name operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Add Substitution Parameter operation

The Add Substitution Parameter operation enables you to add a global substitution parameter to the BMC BladeLogic Network Automation database. The following table describes the elements for the <items> XML element and adapter request for the Add Substitution Parameter operation.
Elements for the <items> XML element and adapter request for the Add Substitution Parameter operation Element Definition Required
466
<substitution-parameter> Contains all of the individual elements that enable you to add a global substitution parameter to the BMC BladeLogic Network Automation database The <substitution-parameter> element contains the following child elements: <key> <name> <value> <dynamic-fields> <sensitive> <key> Specifies the key string associated with a specified global substitution parameter You need this element to modify a global substitution parameter. <name> <value> <dynamic-fields> <sensitive> Specifies the name for the global substitution parameter Specifies the value for the substitution parameter specified in the <name> element
Yes
No
Yes Yes
Specifies a collection of names and values for the global substitution No parameter Decides whether to hide the value of the global substitution parameter No
The following figure shows a sample <items> XML element for the Add Substitution Parameter operation. <items> XML element for the Add Substitution Parameter operation
467
<items> <item> <parameters> <substitution-parameter> <key>a</key> <name>a</name> <value>a</value> <dynamic-fields> <element> <name>a</name> <values> <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values> <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <sensitive>true</sensitive> </substitution-parameter> </parameters> </item> </items>
The following figure shows a sample adapter request for the Add Substitution Parameter operation. Sample adapter request for the Add Substitution Parameter operation
<bmc-configuration-automation-networks-request> <entity>substitution-parameter</entity> <request> <operation-name>add-substitution-parameter</operation-name> <parameters> <substitution-parameter> <name>newParam33</name> <value>xyz</value> <sensitive>true</sensitive> </substitution-parameter> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the response for the sample Add Substitution Parameter operation. Adapter response for the sample Add Substitution Parameter operation
468
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output>582437630-99</output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Modify Substitution Parameter operation

The Modify Substitution Parameter operation enables you to modify an existing global substitution parameter in the BMC BladeLogic Network Automation database. The following table describes the elements for the <items> XML element and adapter request for the Modify Substitution Parameter operation. Elements for the < items > XML element and adapter request for the Modify Substitution Parameter operation Element Definition Required Yes
<substitution-parameter> Contains all of the individual elements that enable you to modify a global substitution parameter in the BMC BladeLogic Network Automation database The <substitution-parameter> element contains the following child elements: <key> <name> <value> <dynamic-fields> <sensitive> For more information about the <substitution-parameter> element, see Request and response for the Device Rollback or Merge By Config Type operation .
The following figure shows a sample <items> XML element for the Modify Substitution Parameter operation. <items> XML element for the Modify Substitution Parameter operation
469
{<items> <item> <parameters> <substitution-parameter> <key>a</key> <name>a</name> <value>a</value> <dynamic-fields>  <element> <name>a</name> <values>  <element>foo</element> <element>bar</element> </values> </element> <element> <name>b</name> <values>  <element>foo</element> <element>bar</element> </values> </element> </dynamic-fields> <sensitive>true</sensitive> </substitution-parameter> </parameters> </item> </items>
The following figure shows a sample adapter request for the Modify Substitution Parameter operation. Sample adapter request for the Modify Substitution Parameter operation
<bmc-configuration-automation-networks-request> <entity>substitution-parameter</entity> <request> <operation-name>modify-substitution-parameter</operation-name> <parameters> <substitution-parameter> <key>582437630-62</key> <name>new-param</name> <value>ttl</value> <sensitive>true</sensitive> </substitution-parameter> </parameters> </request> </bmc-configuration-automation-networks-request>
470
The following figure illustrates the response for the Modify Substitution Parameter operation. Adapter response for the sample Modify Substitution Parameter operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters /> </bmc-configuration-automation-networks-response>
Request and response for the Get Substitution Parameter by Name operation
The Get Substitution Parameter by Name operation retrieves a specific global substitution parameter from the BMC BladeLogic Network Automation database. The following table describes the elements for the <items> XML element and adapter request for the Get Substitution Parameter by Name operation.
Elements for the < items > XML element and adapter request for the Get Substitution Parameter by Name operation Element Definition <name> Required
Specifies the exact name of the required global substitution parameter Yes
This parameter cannot be null.
The following figure shows a sample <items> XML element for the Get Substitution Parameter by Name operation. <items> XML element for the Get Substitution Parameter by Name operation
<items> <item> <parameters> <name></name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Substitution Parameter operation. Sample adapter request for the Get Substitution Parameter operation
471
<bmc-configuration-automation-networks-request> <entity>substitution-parameter</entity> <request> <operation-name>get-substitution-parameter-by-name</operation-name> <parameters> <name>localhostAddress</name> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Get Substitution Parameter operation. Adapter response for the sample Get Substitution Parameter operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <key>582437630-31</key> <name>localhostAddress</name> <value>%localhost.ip_address%</value> <sensitive>false</sensitive> </output> </parameters> </bmc-configuration-automation-networks-response>
Template Group Service operations

The following topics illustrates the adapter request and response for the following Template Group Service operations: Request and response for the Modify Template Group operation Request and response for the Get Template Group By Name operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Modify Template Group operation

The Modify Template Group operation enables you to modify an existing template group in the BMC BladeLogic Network Automation database. The following table describes the elements for the <items> XML element and adapter request for the Modify Template Group operation.
Elements for the <items> XML element and adapter request for the Modify Template Group operation
472
Element <template-group-dto>
Definition Contains all of the individual elements that enable you to modify an existing template group in the BMC BladeLogic Network Automation database The <template-group-dto> element contains the following child elements: <annotation> <dynamic-fields> <key> <name> <substitution-param-check> <templates>
Required Yes
<annotation> <dynamic-fields> <key> <name>
Specifies a short description for the job related to a template group Encloses a dynamic field as a collection of names and values for the template group Specifies the key string for the template group Specifies the name of the template
No No No No No Yes
<substitution-param-check> Indicates whether to check the substitution parameter <templates> Encloses a collection of elements Each element refers to details corresponding to the template contents for each vendor. <overwrite-content> Indicates whether to replace the contents within the stored template group with the content specified in the {{<template-group-dto>]] element If the flag is set to true , stored content is erased and replaced with the content specified in the <template-group-dto> element. If the flag is set to false , the stored content is not changed. No*
The following figure shows a sample <items> XML element for the Modify Template Group operation. <items> XML element for the Modify Template Group operation
<items> <item> <parameters> <template-group-dto> <annotation></annotation> <dynamic-fields> <element> <name>a</name> <values>  <element></element> <element></element> </values>
473
</element> <element> <name></name> <values>  <element></element> <element></element> </values> </element> </dynamic-fields> <key>a</key> <name>a</name> <substitution-param-check></substitution-param-check> <templates>  <element> <contents></contents> <key></key> <device-type-id></device-type-id> <max-release> <build></build> <major></major> <minor></minor> </max-release> <min-release> <build></build> <major></major> <minor></minor> </min-release> <substitution-param-check></substitution-param-check> </element> <element> <contents></contents> <key></key> <device-type-id></device-type-id> <max-release> <build></build> <major></major> <minor></minor> </max-release> <min-release> <build></build> <major></major> <minor></minor> </min-release> <substitution-param-check></substitution-param-check> </element> </templates> </template-group-dto> <overwrite-contents></overwrite-contents>
474
The following figure shows a sample request for the Modify Template Group operation
<bmc-configuration-automation-networks-request> <entity>template-group</entity> <request> <operation-name>modify-template-group</operation-name> <parameters> <template-group-dto> <annotation>modify template</annotation> <key>1034341772-11</key> <name>XYZ</name> <substitution-param-check>false</substitution-param-check> <templates> <element> <contents>logging on</contents> <key>1614687219-33</key> <device-type-id>0</device-type-id> <max-release> <build>*</build> <major>*</major> <minor>*</minor> </max-release> <min-release> <build>*</build> <major>*</major> <minor>*</minor> </min-release> <substitution-param-check>false</substitution-param-check> </element> </templates> </template-group-dto> <overwrite-contents>true</overwrite-contents> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Modify Template Group operation. Adapter response for the sample Modify Template Group operation
475
Request and response for the Get Template Group By Name operation
The Get Template Group By Name operation allows you to retrieve a specific template group from the BMC BladeLogic Network Automation database. The following table describes the elements for the <items> XML element and adapter request for the Get Template Group By Name operation.
Elements for the <items> XML element and adapter request for the Get Template Group By Name operation Element Definition <name> Required
Specifies the name of the required template group Yes
The following figure shows a sample <items> XML element the adapter response for the sample Get Template Group By Name operation. < items > XML element for the Get Template Group By Name operation
<items> <item> <parameters> <name></name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Template Group By Name operation. Sample adapter request for the Get Template Group By Name operation
476
<bmc-configuration-automation-networks-request> <entity>template-group</entity> <request> <operation-name>get-template-group-by-name</operation-name> <parameters> <name>Syslog</name> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Get Template Group By Name operation. Adapter response for the sample Get Template Group By Name operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <annotation>syslog configuration</annotation> <dynamic-fields> <element /> </dynamic-fields> <key>1034341772-1</key> <name>Syslog</name> <substitution-param-check>false</substitution-param-check> <templates> <element> <contents>logging on logging facility local7 logging trap notifications logging ${agent.localhostAddress} end </contents> <key>1614687219-6</key> <device-type-id>0</device-type-id> <max-release> <build>*</build> <major>*</major> <minor>*</minor> </max-release> <min-release> <build>*</build> <major>*</major> <minor>*</minor> </min-release> <substitution-param-check>false</substitution-param-check> </element> <element> <contents>config sys syslog host 10 create
477
config config config config
sys sys sys sys
logging logging logging logging exit
syslog host 10 address ${agent.localhostAddress} syslog host 10 facility local7 syslog host 10 severity info syslog state enable </contents> <key>1614687219-14</key> <device-type-id>27</device-type-id> <max-release> <build>*</build> <major>*</major> <minor>*</minor> </max-release> <min-release> <build>*</build> <major>*</major> <minor>*</minor> </min-release> <substitution-param-check>false</substitution-param-check> </element> <element> <contents>config term enable level informational nv-level serious remote enable remote address ${agent.localhostAddress} remote level informational </contents> <key>1614687219-5</key> <device-type-id>32</device-type-id> <max-release> <build>*</build> <major>*</major> <minor>*</minor> </max-release> <min-release> <build>*</build> <major>*</major> <minor>*</minor> </min-release> <substitution-param-check>false</substitution-param-check> </element> </templates>
478
Job Approval Type Service operations

The following topics illustrates the adapter request and response for the Job Approval Type Service operation, Get Job Approval Types. Request and response for the Get Job Approval Types operation
Request and response for the Get Job Approval Types operation
The Get Job Approval Types operation enables you to retrieve information about all job approvers existing in the BMC BladeLogic Network Automation application. The following figure shows a sample <items> XML element for the Get Job Approval Types operation. <items> XML element for the Get Job Approval Types operation
<items> <item> <parameters /> </item> </items>
The following figure shows a sample adapter request for Get Job Approval Types operation. Sample adapter request for the Get Job Approval Types operation
<bmc-configuration-automation-networks-request> <entity>job-approval-type</entity> <request> <operation-name>get-job-approval-types</operation-name> <parameters /> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the Get Job Approval Types operation. Adapter response for the Get Job Approval Types operation
479
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <key>572010576-1</key> <name>admin</name> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
Group Service operation

The following topic illustrates the adapter request and response for the Group Service operation, Get Simple Groups. Request and response for the Get Simple Groups operation
Request and response for the Get Simple Groups operation

The Get Simple Groups operation enables you to retrieve the list of simple groups that matches a specified filter criteria. The following table describes the elements for the <items> XML element and adapter request for the Get Simple Groups operation.
Elements for the < items > XML element and adapter request for the Get Simple Groups operation Element Definition Required
480
<group-filter>
Contains all of the individual elements that enable you to retrieve the list of simple groups that matches a specified filter criteria The <group-filter> element contains the following child elements: <dynamic-field-range> <dynamic-fields> <key> <name-match> <show-auto-groups> <show-simple-groups> Note: The <group-filter> element is required, but none of its child elements is required.
Yes
<dynamic-field-range> Specifies the filtering components using dynamic fields (for example, Device inventory, Jobs, and Rule Sets) <dynamic-fields> <key> <name-match> <realm-name-match> <show-auto-groups> Encloses a dynamic field as a collection of names and values that can be used for groups Specifies the key string associated with each group Specifies the name of a group Specifies the name of a realm Groups a device in show-auto-groups Default groups exist for different vendors. When you add a device without specifying any group, the device is grouped into these default groups. <show-simple-groups> Specifies user-created groups
No No No No No No
No
The following figure shows a sample <items> XML element for the Get Simple Groups operation. < items > XML element for the Get Simple Groups operation
481
<items> <item> <parameters> <group-filter> <dynamic-field-range> <element> <dynamic-field-key-string></dynamic-field-key-string> <range> <key>a</key> </range> </element> <element> <dynamic-field-key-string>b</dynamic-field-key-string> <range> <key>b</key> </range> </element> </dynamic-field-range> <dynamic-fields> <element> <name>a</name> <value>a</value> </element> <element> <name>b</name> <value>b</value> </element> </dynamic-fields> <key>a</key> <name-match>a</name-match> <realm-name-match>a</realm-name-match> <show-auto-groups>true</show-auto-groups> <show-simple-groups>true</show-simple-groups> </group-filter> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Simple Groups operation. Sample adapter request for the Get Simple Groups operation
482
<bmc-configuration-automation-networks-request> <entity>group</entity> <request> <operation-name>get-simple-groups</operation-name> <parameters> <group-filter> <show-auto-groups>true</show-auto-groups> <show-simple-groups>true</show-simple-groups> </group-filter> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure shows the adapter response for the sample Get Simple Groups operation. Adapter response for the sample Get Simple Groups operation
483
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <key>1415436101-11</key> <name>DeviceType.Cisco IOS Switch/Router</name> <realm> <key>955703509-1</key> <name>Default</name> </realm> <auto-group>false</auto-group> <device-count>0</device-count> <devices> <element /> </devices> </element> <element> <dynamic-fields> <element> <name>Description</name> <values> <element></element> </values> </element> <element> <name>Point of Contact</name> <values> <element></element> </values> </element> </dynamic-fields> <key>1415436101-31</key> <name>myGroup</name> <realm> <key>955703509-1</key> <name>Default</name> </realm> <auto-group>false</auto-group> <device-count>0</device-count> <devices> <element /> </devices> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
Predefined Jobs operation
484
The following topics illustrates the adapter requests and responses for the following Predefined Job operations: Request and response for the Get All Predefined Job Names operation Request and response for the Get Predefined Job Names operation Request and response for the Get Predefined Job Parameter Types operation Request and response for the Submit Job operation Request and response for the Validate Predefined Job Parameters operation Request and response for the Get All Shared Runtime Parameters operation
Request and response for the Get All Predefined Job Names operation
The Get All Predefined Job Names operation enables you to retrieve a list of the names of all predefined jobs in BMC BladeLogic Network Automation. The following table shows a sample <items> XML element for the Get All Predefined Job Names operation. <items> XML element for the Get All Predefined Job Names operation
<items> <item> <parameters/> </item> </items>
The following figure shows a sample adapter request for the Get All Predefined Job Names operation. Sample adapter request for the Get All Predefined Job Names operation
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>get-all-predefined-job-names</operation-name> <parameters/> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get All Predefined Job Names operation. Adapter response for the Get All Predefined Job Names operation
485
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element>Job1</element> <element>testjob</element> </output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Get Predefined Job Names operation
The Get Predefined Job Names operation enables you to retrieve a list of the names of all predefined jobs that matches the specified filter criteria. The following table describes the elements for the <items> XML element and adapter request for the Get Predefined Job Names operation.
Elements for the < items > XML element and adapter request for the for the Get Predefined Job Names operation Element Definition Required Yes
<name-match> Contains a string name pattern, which includes wildcard characters For example, to search predefined job names starting with test, this element must contain test*.
The following figure shows a sample <items> XML element for the Get Predefined Job Names operation. < items > XML element for the Get Predefined Job Names operation
<items> <item> <parameters> <name-match></name-match> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Predefined Job Names operation. Sample adapter request for the Get Predefined Job Names operation
486
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>get-predefined-job-names</operation-name> <parameters> <name-match>test*</name-match> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get Predefined Job Names operation. Adapter response for the Get Predefined Job Names operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element>test1</element> </output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Get Predefined Job Parameter Types operation
The Get Predefined Job Parameter Types operation enables you to retrieve the set of runtime parameters required for the specified predefined job. The following table describes the elements for the <items> XML element and adapter request for the Get Predefined Job Parameter Types operation.
Elements for the < items > XML element and adapter request for the Get Predefined Job Parameter Types operation Element Definition Required Yes
<predefined-job-name> Specifies the name of the predefined job for which the runtime parameters are to be retrieved
The following figure shows a sample <items> XML element for the Get Predefined Job Parameter Types operation.
<items> XML element for the Get Predefined Job Parameter Types operation
487
{{<items> <item> <parameters> <predefined-job-name></predefined-job-name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get Predefined Job Parameter Types operation. Sample adapter request for the Get Predefined Job Parameter Types operation
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>get-predefined-job-param-types</operation-name> <parameters> <predefined-job-name>test</predefined-job-name> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get Predefined Job Parameter Types operation. Adapter response for the sample Get Predefined Job Parameter Types operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <action-runtime-param-types/> <change-id-param-type> <enum-values/> <name>ChangeId</name> <required>false</required> <type>TEXT</type> </change-id-param-type> <job-dynamic-field-param-types> <element> <default-value>Risk Level 2</default-value> <enum-values> <element>Risk Level 1</element> <element>Risk Level 2</element> <element>Risk Level 3</element> <element>Risk Level 4</element> <element>Risk Level 5</element> </enum-values>
488
<name>Risk Level</name> <required>false</required> <type>ENUMERATION</type> </element> <element> <default-value>Asset Lease</default-value> <enum-values> <element>Asset Configuration</element> <element>Asset Lease</element> <element>Asset Maintenance</element> <element>Asset Management</element> <element>Change</element> <element>Project</element> <element>Purchase Requisition</element> <element>Release</element> </enum-values> <name>Change Type</name> <required>false</required> <type>ENUMERATION</type> </element> <element> <default-value>Minor/Localized</default-value> <enum-values> <element>Extensive/Widespread</element> <element>Minor/Localized</element> <element>Moderate/Limited</element> <element>Significant/Large</element> </enum-values> <name>Impact</name> <required>false</required> <type>ENUMERATION</type> </element> <element> <default-value>sfvsfv</default-value> <enum-values/> <name>Comments</name> <required>false</required> <type>TEXT</type> </element> </job-dynamic-field-param-types> <run-at-time-param-type> <enum-values/> <name>RunAtTime</name> <required>true</required> <type>TEXT</type> </run-at-time-param-type> <runtime-span-prompts/> <task-id-param-type> <enum-values/> <name>TaskId</name> <required>false</required> <type>TEXT</type> </task-id-param-type>
489
Request and response for the Submit Job operation

The Submit Job operation uses the names of the predefined job and a set of job parameters, executes the job, and returns the job number. The following table describes the elements for the <items> XML element and adapter request for the Submit Job operation.
Elements for the < items > XML element and adapter request for the Submit Job operation Element <predefined-job-name> <job-params> Definition Specifies the name of the predefined job Required Yes
Contains all of the individual elements that execute the Yes job and return the job number The <job-params> element contains the following child elements: <action-runtime-param-values> <action-sequence-number> <runtime-params> <change-id> <job-approval-type> <job-dynamic-field-values> <run-at-time> <runtime-span-values> <span-type> <span-name> <span-prompt> <shared-runtime-parameter-values> <task-id> <realm-name>
<action-runtime-param-values> <action-sequence-number>
Specifies the runtime values for the action that Conditional corresponds to a sequence number in a predefined job Specifies the sequence number of the action that the parameters are associated with, in the related predefined job Specifies name-value pairs for the action that corresponds to a sequence number in the predefined job Conditional
<runtime-params>
Conditional
490
<change-id>
Specifies the Change ID when BMC Remedy IT Service Management integration is enabled If the integration is enabled, the Change ID field relates jobs to BMC Remedy Action Request System change requests. If the integration is disabled, the field representing this element is free-form, allowing users to use a two-level system to track change requests.
No
<job-approval-type>
Specifies the name of a job approval type, if job approval is required for the job prepared from the associated predefined job Specifies the values for the job dynamic fields that are needed while creating a job from a predefined job Specifies the time at which the job should be executed
Conditional
<job-dynamic-field-values> <run-at-time>
No Yes
Valid values: Now or when approved Date format in MM:dd:yy HH:mm (for example, 08:20:09 16:28) <runtime-span-values> <span-type> Specifies the values for the span prompts for runtime spans in the predefined job Specifies the following span types: realm group device Note: The values are not case-sensitive. <span-name> <span-prompt> Specifies the name of the span for the type specified in the <span-type> element Specifies the prompt for a runtime span for the predefined job Conditional Conditional Conditional Conditional Conditional
<shared-runtime-parameter-values> Specifies the values for the shared runtime parameters in the associated predefined job Note: Use this element with BMC BladeLogic Network Automation application version 5.4 and later. <task-id> Specifies the Task ID when BMC Remedy IT Service Management integration is enabled If the integration is disabled, the field representing this element is free-form, allowing users to use a two-level system to track change requests. If the integration is enabled, the Task ID field relates jobs to BMC Remedy Action Request System change requests. <realm-name> Specifies the realm in which the group must be searched
No
Conditional
491
<wait-for-completion>
Indicates whether the job should run synchronously If the flag is true , the system waits for the job to complete before returning. If the flag is false , the system returns to the client without waiting for the job to finish.
Yes
The following figure shows a sample <items> XML element for the Submit Job operation. < items > XML element for the Submit Job operation
<items> <item> <parameters> <predefined-job-name></predefined-job-name> <job-params> <action-runtime-param-values> <element> <action-sequence-number></action-sequence-number> <runtime-params> <element> <name></name> <value></value> </element> </runtime-params> </element> </action-runtime-param-values> <change-id></change-id> <job-approval-type></job-approval-type> <job-dynamic-field-values> <element> <name></name> <value></value> </element> </job-dynamic-field-values> <run-at-time></run-at-time> <runtime-span-values> <element> <realm-name></realm-name> <span-name></span-name> <span-prompt></span-prompt> <span-type></span-type> </element> <element> <span-name>-01</span-name> <span-prompt></span-prompt> <span-type></span-type> </element> </runtime-span-values> <shared-runtime-parameter-values> <element> <name></name>
492
<value></value> </element> <element> <name></name> <value></value> </element> <element> <name></name> <value></value> </element> <element> <name></name> <value></value> </element> </shared-runtime-parameter-values> <task-id></task-id> </job-params> <wait-for-completion></wait-for-completion>
493
Note The Get All Shared Runtime Parameters operation is supported by BMC BladeLogic Network Automation application v5.4 and later. Therefore, use the <shared-runtime-parameter-values> element mentioned in the sample <items> XML with v5.4 and later of the BMC BladeLogic Network Automation application.
The following figure shows a sample adapter request for the Submit Job operation. Sample adapter request for the Submit Job operation
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>submit-job</operation-name> <parameters> <predefined-job-name>check</predefined-job-name> <job-params> <action-runtime-param-values> <element> <action-sequence-number>1</action-sequence-number> <runtime-params> <element> <name> IP address of node to ping</name> <value>10.254.1.80</value> </element> </runtime-params> </element> </action-runtime-param-values> <change-id>changeid01</change-id> <job-approval-type>Admin</job-approval-type> <job-dynamic-field-values> <element> <name>Commnets</name> <value>Testing...Testing..</value> </element> </job-dynamic-field-values> <run-at-time>Now or when approved</run-at-time> <runtime-span-values> <element> <realm-name>default</realm-name> <span-name>DeviceType.Cisco IOS Switch/Router</span-name> <span-prompt>A</span-prompt> <span-type>Group</span-type>
494
</element> <element> <span-name>cisco1760-01</span-name> <span-prompt>A</span-prompt> <span-type>Device</span-type> </element> </runtime-span-values> <shared-runtime-parameter-values> <element> <name>res_LGPD_Pool_Name</name> <value>hello</value> </element> <element> <name>res_LGPD_Server_HostName</name> <value>hello2</value> </element> <element> <name>res_LGPD_Server_Address</name> <value>hello3</value> </element> <element> <name>res_LGPD_Server_Port</name> <value>hello4</value> </element> </shared-runtime-parameter-values> <task-id>taskid01</task-id> </job-params> <wait-for-completion>false</wait-for-completion>
495
</parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Submit Job operation. Adapter response for the sample Submit Job operation
Request and response for the Validate Predefined Job Parameters operation
The Validate Predefined Job Parameters operation uses the same parameters as the Submit Job operation. The Validate Predefined Job Parameters operation does not run the job; instead, it validates the information specified for submitting a job. If the operation executes properly, this operation returns a null value; else, it returns a set of error messages. The following table describes the elements for the <items> XML element and adapter request for the Validate Predefined Job Parameters operation.
Elements for the < items > XML element and adapter request for the Validate Predefined Job Parameters operation Element Definition Required Yes Yes
<predefined-job-name> Specifies the name of the predefined job for which the runtime parameters are to be retrieved <job-params> Contains all of the individual elements that enable you validate the information specified for submitting a job; see [elements] for information about the <job-params> element
<wait-for-completion> Indicates whether the job should run synchronously If the flag is set to true, the system waits for the job to complete before returning. If the flag is set to false, the system returns to the client without waiting for the job to finish.
Yes
The following figure shows a sample <items> XML element for the Validate Predefined Job Parameters Types operation. <items> XML element for the Validate Predefined Job Parameters operation
496
<items> <item> <parameters> <predefined-job-name></predefined-job-name> <job-params> <action-runtime-param-values> <element> <action-sequence-number></action-sequence-number> <runtime-params> <element> <name></name> <value></value> </element> </runtime-params> </element> </action-runtime-param-values> <change-id></change-id> <job-approval-type></job-approval-type> <job-dynamic-field-values> <element> <name></name> <value></value> </element> </job-dynamic-field-values> <run-at-time></run-at-time> <runtime-span-values> <element> <realm-name></realm-name> <span-name></span-name> <span-prompt></span-prompt> <span-type></span-type> </element> <element> <span-name></span-name> <span-prompt></span-prompt> <span-type></span-type> </element> </runtime-span-values> <task-id></task-id> </job-params> <wait-for-completion></wait-for-completion> </parameters> </item> </items>
The following figure shows a sample adapter request for the Validate Predefined Job Parameters operation. Sample adapter request for the Validate Predefined Job Parameters operation
497
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>validate-predefined-job-params</operation-name> <parameters> <predefined-job-name>check</predefined-job-name> <job-params> <action-runtime-param-values> <element> <action-sequence-number>1</action-sequence-number> <runtime-params> <element> <name> IP address of node to ping</name> <value>10.254.1.80</value> </element> </runtime-params> </element> </action-runtime-param-values> <change-id>changeid01</change-id> <job-approval-type>Admin</job-approval-type> <job-dynamic-field-values> <element> <name>Commnets</name> <value>Testing</value> </element> </job-dynamic-field-values> <run-at-time>Now or when approved</run-at-time> <runtime-span-values> <element> <realm-name>default</realm-name> <span-name>DeviceType.Cisco IOS Switch/Router</span-name> <span-prompt>A</span-prompt> <span-type>Group</span-type> </element> <element> <span-name>cisco1760-01</span-name> <span-prompt>A</span-prompt> <span-type>Device</span-type> </element> </runtime-span-values> <task-id>taskid01</task-id> </job-params> <wait-for-completion>false</wait-for-completion> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Validate Predefined Job Parameters operation. Adapter response for the sample Validate Predefined Job Parameters operation
498
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output></output> </parameters> </bmc-configuration-automation-networks-response>
Request and response for the Get All Shared Runtime Parameters operation
The Get All Shared Runtime Parameters operation enables you to retrieve a list of all shared run-time parameters for a given predefined job. This operation is supported by BMC BladeLogic Network Automation application v5.4 and later. The following table describes the elements for the <items> XML element and adapter request for the Get All Shared Runtime Parameters operation.
Elements for the < items > XML element and adapter request for the Get All Shared Runtime Parameters operation Element Definition Required Yes
<predefined-job-name> Specifies the name of the predefined job for which shared runtime parameters are to be retrieved
The following figure shows a sample <items> XML element for the Get All Shared Runtime Parameters operation. <items> XML element for the Get All Shared Runtime Parameters operation
<items> <item> <parameters> <predefined-job-name>testPdJobs</predefined-job-name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get All Shared Runtime Parameters operation. Sample adapter request for the Get All Shared Runtime Parameters operation
499
<bmc-configuration-automation-networks-request> <entity>predefined-job</entity> <request> <operation-name>get-all-shared-runtime-parameters</operation-name> <parameters> <predefined-job-name>testPdJobs</predefined-job-name> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get All Shared Runtime Parameters operation. Adapter response for the sample Get All Shared Runtime Parameters operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <key>704278632-49</key> <name>testPassword</name> <value>admin</value> <param-number>1</param-number> <type>Password</type> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
Firewall Service operations

The Firewall Service operations are supported in BMC BladeLogic Network Automation 8.1.01 only. The following topics illustrate the adapter requests and responses for the Firewall Service operations: Request and response for the Get All Firewall Rules operation Request and response for the Overwrite Firewall Rules operation Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Get All Firewall Rules operation
The Get All Firewall Rules operation enables you to retrieve the rules in a firewall for a given Zone in a specified container. The following table describes the elements for the <items> XML element and adapter request for the Get All Firewall Rules operation.
500
Elements for the <items> XML element and adapter request for the Get All Firewall Rules operation Element Definition Required Yes
<container-name> Specifies the container that contains the Zone <zone-name>
Specifies the Zone whose firewall rules you want to retrieve Yes
The following figure shows a sample <items> XML element for the Get All Firewall Rules operation. <items> XML element for the Get All Firewall Rules operation
<items> <item> <parameters> <container-name>Container1</container-name> <zone-name>Zone 1</zone-name> </parameters> </item> </items>
The following figure shows a sample adapter request for the Get All Firewall Rules operation. Sample adapter request for the Get All Firewall Rules operation
<bmc-configuration-automation-networks-request> <soap-version>1.1</soap-version> <entity>firewall</entity> <request> <operation-name>get-all-firewall-rules</operation-name> <parameters> <container-name>Container1</container-name> <zone-name>Zone 1</zone-name> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Get All Firewall Rules operation. Note The adapter response contains only those elements that do not contain empty values. Adapter response for the Get All Firewall Rules operation
501
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <element> <description>Update 4</description> <destination-host-address>10.10.10.12</destination-host-address> <destination-network-address>10.20.20.20 </destination-network-address> <destination-network-mask>255.255.255.255 </destination-network-mask> <destination-port>600</destination-port> <enabled-flag>true</enabled-flag> <permit-flag>false</permit-flag> <source-host-address>20.20.20.22</source-host-address> <source-network-address>20.20.20.30</source-network-address> <source-network-mask>255.255.255.255</source-network-mask> <transport-protocol>100</transport-protocol> </element> <element> <description>New Update 5</description> <destination-host-address>10.10.10.15 </destination-host-address> <destination-port>200</destination-port> <enabled-flag>true</enabled-flag> <permit-flag>false</permit-flag> <source-host-address>20.20.20.25</source-host-address> <transport-protocol>100</transport-protocol> </element> </output> </parameters> </bmc-configuration-automation-networks-response>
The following table describes the response elements for the Get All Firewall Rules operation. Response Elements for the Get All Firewall Rules operation Element <output> Definition Contains the rules in the firewall for the given Zone
502
<element>
Contains the individual firewall rule information The <element> element contains the following child elements: <description> <destination-host-address> <destination-network-address> <destination-network-mask> <destination-port> <enabled-flag> <permit-flag> <source-host-address> <source-network-address> <source-network-mask> <transport-protocol>
<description> <destination-host-address>
Contains the description of the specified rule Contains the address of the destination host that is involved when blocking a particular host
<destination-network-address> Contains the address of the destination subnet involved when blocking a range of hosts <destination-network-mask> <destination-port> <enabled-flag> <permit-flag> <source-host-address> <source-network-address> <source-network-mask> <transport-protocol> Contains the mask of the destination subnet involved when blocking a range of hosts Contains the destination port being blocked Indicates whether the rule is enabled or disabled Indicates whether the rule is permitting or denying the specified traffic Contains the address of the source involved when blocking a particular host Contains the address of the source subnet involved when blocking a range of hosts Contains the mask of the source subnet involved when blocking a range of hosts Contains the identifier for the transport protocol being blocked
Request and response for the Overwrite Firewall Rules operation

The Overwrite Firewall Rules operation enables you to create and execute a job that overwrites or appends all the rules in the specified firewall. The following table describes the elements for the <items> XML element and adapter request for the Overwrite Firewall Rules operation. Elements for the <items> XML element and adapter request for the Overwrite Firewall Rules operation Element <container-name> Definition Specifies the container that contains the specified Zone Required Yes
503
<zone-name> <context-host-address>
Specifies the Zone whose firewall rules you want to overwrite or append Specifies the address of the host, in dotted decimal format, which is the source or the destination in the rule that is to be overwritten Note If <context-host-address> is not specified or contains an empty value, all existing rules are replaced. If <context-host-address> is not empty, only those rules with a matching <source-host-address> or <destination-host-address> are replaced.
Yes No
<firewall-rules> <element>
Specifies the firewall rules that you want to overwrite or append Specifies the individual firewall rule information that you want to overwrite or append The <element> element contains the following child elements: <description> <destination-host-address> <destination-network-address> <destination-network-mask> <destination-port> <enabled-flag> <permit-flag> <source-host-address> <source-network-address> <source-network-mask> <transport-protocol>
Yes Yes
<description> <destination-host-address>
Specifies the description of the specified rule Specifies the address of the destination host that is involved when blocking a particular host Note For "any" destination, specify 0.0.0.0 as the <destination-network-address> and 0.0.0.0 as the <destination-network-mask>.
No
Conditional; not required if you <destination-network-a and <destination-network-m
<destination-network-address> Specifies the address of the destination subnet involved when blocking a range of hosts <destination-network-mask> Specifies the mask of the destination subnet involved when blocking a range of hosts
Conditional; not required if you <destination-host-addr
Conditional; not required if you <destination-host-addr
504
<destination-port> <enabled-flag> <permit-flag>
Specifies the destination port being blocked Specifies whether the rule is enabled or disabled Valid values: true, false (default) Specifies whether the rule permits or denies the specified traffic Valid values: true, false (default) Specifies the address of the source involved when blocking a particular host <source-host-address> can be a computer name, such as java.sun.com, or a textual representation of its IP address in dotted decimal format, such as 192.9.162.55. Address strings returned by the BMC BladeLogic Network Automation application are always in dotted decimal format.
No No No
<source-host-address>
Conditional; not required if you <source-network-addres <source-network-mask>
<source-network-address>
Specifies the address of the source subnet involved when blocking a range of hosts <source-network-address> can be a computer name, such as java.sun.com, or a textual representation of its IP address in dotted decimal format, such as 192.9.162.55. Address strings returned by the BMC BladeLogic Network Automation application are always in dotted decimal format. Note For "any" destination, specify 0.0.0.0 as the <destination-network-address> and 0.0.0.0 as the <destination-network-mask>.
Conditional; not required if you <source-host-address>
<source-network-mask>
Specifies the mask of the source subnet involved when blocking a range of hosts Note For "any" destination, specify 0.0.0.0 as the <destination-network-address> and 0.0.0.0 as the <destination-network-mask>.
Conditional; not required if you <source-host-address>
<transport-protocol>
Specifies the identifier for the transport protocol being No blocked
The following figure shows a sample <items> XML element for the Overwrite Firewall Rules operation. <items> XML element for the Overwrite Firewall Rules operation
505
<items> <item> <parameters> <container-name>Container1</container-name> <zone-name>Zone 1</zone-name> <context-host-address>20.20.20.20</context-host-address> <firewall-rules> <element> <description>New Update 5</description> <destination-host-address>10.10.10.15</destination-host-address> <destination-network-address>10.20.20.20</destination-network-address> <destination-network-mask>255.255.255.255</destination-network-mask> <destination-port>200</destination-port> <enabled-flag>true</enabled-flag> <permit-flag>false</permit-flag> <source-host-address>20.20.20.25</source-host-address> <source-network-address>20.20.20.30</source-network-address> <source-network-mask>255.255.255.255</source-network-mask> <transport-protocol>100</transport-protocol> </element> </firewall-rules> </parameters> </item> </items>
The following figure shows a sample adapter request for the Overwrite Firewall Rules operation. Sample adapter request for the Overwrite Firewall Rules operation
<bmc-configuration-automation-networks-request> <entity>firewall</entity> <request> <operation-name>overwrite-firewall-rules</operation-name> <parameters> <container-name>Container1</container-name> <zone-name>Zone 1</zone-name> <context-host-address>20.20.20.20</context-host-address> <firewall-rules> <element> <description>New Desc</description> <destination-host-address>10.10.10.15</destination-host-address> <destination-port>200</destination-port> <enabled-flag>true</enabled-flag> <permit-flag>false</permit-flag> <source-host-address>20.20.20.25</source-host-address> <transport-protocol>100</transport-protocol> </element> </firewall-rules> </parameters> </request> </bmc-configuration-automation-networks-request>
The following figure illustrates the adapter response for the sample Overwrite Firewall Rules operation when it
506
executes successfully. Adapter response for the successful Overwrite Firewall Rules operation
The following table describes the response elements for the successful Get All Firewall Rules operation.
Response Elements for the successful Get All Firewall Rules operation Element Definition
<parameters> Is empty when the operation is executed successfully The following figure illustrates the adapter response for the sample Overwrite Firewall Rules operation when it fails to execute. Adapter response for the failed Overwrite Firewall Rules operation
<bmc-configuration-automation-networks-response> <metadata> <status>success</status> </metadata> <parameters> <output> <metadata> <status>error</status> <error>Error occurred processing request data call a web service.
Summary: Failed to
Caused by: Summary: Input contains invalid rules: The firewall rule destination network address should not be populated when destination host address is populated. The firewall rule destination network mask should not be populated when destination host address is populated. The firewall rule source network address should not be populated when source host address is populated. The firewall rule source network mask should not be populated when source host address is populated. </error> </metadata> </output> </parameters> </bmc-configuration-automation-networks-response>
The following table describes the response elements for the failed Get All Firewall Rules operation.
Response Elements for the failed Get All Firewall Rules operation
507
Element
Definition
<parameters> Contains the child elements <output> <status> <error> Contains metadata information Contains the status of execution The value of <status> is error in this case. Contains the error message
Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Network Automation
This topic provides information for troubleshooting issues specific to the BMC Atrium Orchestrator application adapter for BMC BladeLogic Network Automation. Message: Java language binding generation failed, unable to find valid certification path to requested target. Explanation: The adapter fails to install the certificate for the following reasons: No port is specified in the SOAP URL. Two or more adapters that use the Web Services adapter are enabled with automatic certificate installation elements set to true. The SSL handshake exception prevents the certificate from being loaded; as a result, the adapter stops responding. User response: Use one of the following corrective actions: Specify the port in the SOAP URL of the BMC BladeLogic Network Automation application. Add <allow-unsigned-certificate>true</allow-unsigned-certificate> in the adapter configuration, if it is not already present. Message: Java language binding generation failed. The Axis SOAP stack tool "WSDL2Java" failed to produce a Java language binding for the specified WSDL or Message: Java language binding generation failed. Summary: java.security.cert.CertificateException: No subject alternative names present Explanation: When you specify the IP address of the BMC BladeLogic Network Automation application server in the SOAP URL that uses the HTTPS protocol, the adapter tries to establish a secure connection with the BMC BladeLogic Network Automation application by using the specified IP address. However, for a secure connection, the SSL certificate is issued to a computer name and not the IP address. User response: In the SOAP URL, instead of the IP address, specify the host name or computer name of the BMC BladeLogic Network Automation server, which is located at the top right corner of the application. Message: Job not approved by Do External Approve operation Explanation: If a job has the approver type set to any value other than remedy approval or other third-party integrated software, the Do External Approve operation does not approve the job. User response: Install BMC Remedy AR System or the third-party application and integrate it with the BMC BladeLogic Network Automation application. Message: Adapter response displays <status>error</status> instead of success for Do Approve Job by Job Id operation
508
Explanation: This is a vendor API issue. With BMC BladeLogic Network Automation version 5.4.1, when an already approved or executed job is reapproved by the Do Approve Job by Job Id operation or other approving operations, the adapter response displays error instead of success. User response: You do not need to take any action. For BMC BladeLogic Network Automation versions earlier than 5.4.1, the responses for all the approval operations returned the following numeric values: -1: Job not found 0: No job approved (because it was already approved or does not need approval) >1: Number of jobs approved (can be more than 1 if the Change ID or some other non-unique identifier is specified) Message: Errors occurred while executing Custom Action job Explanation: This was a vendor API issue and has been fixed in BMC BladeLogic Network Automation version 5.2.00.46. Message: Error occurred processing request data Summary: Failed to call a web service. Caused by: Summary: Validation errors occurred in job: Action #1: Action guid value does not refer to a valid action type. Explanation: Starting with BMC BladeLogic Network Automation version 5.3.01, the <id> element changed to <guid>. User response: Use the <guid> element instead of the <id> element. Message: Execution not yet completed for job BCAN Explanation: The Get Span Action Results operation can be executed only when the job status is completed. User response: Execute the Get Span Action Results operation on completed jobs only. Message: Unsigned certificates not supported Explanation: The BMC BladeLogic Network Automation application does not support unsigned certificates. User response: Starting with BMC Atrium Orchestrator 20.11.01, the <allow-unsigned-certificate> element specifies whether to allow unsigned certificates from trusted zones. Use this element only if you want to establish a secure connection with the BMC BladeLogic Network Automation application and want to allow an unsigned SSL certificate. If the servers certificate is signed, you do not need to use this element. Message: Adapter request fails to execute Explanation: The adapter requests fails to execute when the adapter is enabled for secure communication. User response: Use the following procedure to debug an adapter request for secure communication: 1. Ensure that the certificate issued by the BMC BladeLogic Network Automation server contains the host name and not the IP address. 2. Ensure that the host name and not the IP address is specified in the <soap-url> element in the adapter configuration as follows: <soap-url>https:// hostName:portNumber </soap-url>
The port number is required; specify it even if it is the default port (443). 3. Restart the configuration distribution peer (CDP) services.
509
BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation
Application adapters enable BMC Atrium Orchestrator workflow processes to perform specialized functions and interact with external applications. The BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation provides the interface between the workflow processes and BMC BladeLogic Server Automation. The BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation enables you to design and develop run books and IT process automation solutions for server configuration, compliance, discovery, and virtualization. The application adapter for BMC BladeLogic Server Automation contains an actor adapter and an adapter module, which comprise workflow processes that perform the standard application actions available through the BMC BladeLogic Server Automation interface. The application actions that you can perform using this adapter belong to the functional areas including, but not limited to: access control compliance job management
Getting started with the BMC BladeLogic Server Automation adapter

This section contains information about: Prerequisites for the BMC BladeLogic Server Automation adapter Supported versions of BMC BladeLogic Server Automation Configuring the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation
Prerequisites for the BMC BladeLogic Server Automation adapter

The following requirements must be met before you use the adapter: BMC BladeLogic Server Automation Console and NSH must be installed on the peer where the adapter is enabled. If the BMC BladeLogic Server Automation server is running on Windows, the peer service must be running with administrative rights. If you upgrade the peer on which the adapter is enabled, verify that the peer service is running with administrative rights. You must configure the adapter to work with the BMC BladeLogic single sign-on (SSO) feature. If the BMC BladeLogic client is installed on the computer after the installation of BMC Atrium Orchestrator, you must restart the peer before enabling the adapter. For using the Active Directory/Kerberos authentication mechanism, you must configure Active Directory and the Kerberos protocol on the peer where the adapter is enabled. For executing Jython commands using the adapter, you must install Jython on the peer where the adapter is enabled. Additionally, if you want to use the adapter with the BMC BladeLogic Web Services interface, you must enable web services on the BMC BladeLogic Application Server. For more information about configuring the BMC BladeLogic Web Services interface, see BMC BladeLogic Server Automation Web Services Developer Guide. To enable web services 1. On the Application Server, start the blasadmin utility and type the following command: set AppServer enableWebServices true 2. Restart the Application Server.
Supported versions of BMC BladeLogic Server Automation

510
The adapter supports the following versions of BMC BladeLogic Server Automation: 7.4.2 7.4.3 7.5 7.6 8.0 8.1 The supported platforms for the BMC BladeLogic Server Automation server are: Microsoft Windows Linux Oracle Solaris For detailed information about the operating system support, see the BMC Atrium Orchestrator Content Release Notes.
Configuring the BMC Atrium Orchestrator Application Adapter for BMC BladeLogic Server Automation
You configure an adapter in BMC Atrium Orchestrator Grid Manager. The configuration provides information about how the adapter interacts with BMC BladeLogic Server Automation. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view provides an easy-to-use interface for configuring the actor adapter. You can also switch to the XML view to configure the adapter using XML only. However, after you switch to the XML view and save the configuration in the XML, you cannot thereafter use the form view for modifying the adapter configuration. Note A monitor adapter is not available for BMC BladeLogic Server Automation.
To add a new actor adapter configuration

1. Log on to BMC Atrium Orchestrator Grid Manager. 2. To access the adapters page, click the Manage tab, and click the Adapters tab. 3. On the Adapters in Repository page, select the check box corresponding to ro-adapter-bladelogic-server-automation. 4. Click Add to Grid. The adapter is now listed under Adapters on Grid. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, configure the adapter by using the form view, or skip to step 7 to configure the adapter by using the XML view: a. Enter BladeLogic Adapter as the name for the adapter. This is the default adapter name used by the processes in the BMC_BladeLogic-AD-Operations_Manager module. b. Enter a description for the adapter. c. Under Properties, enter the values for the configuration elements, which are described in Adapter configuration samples and elements . Note Include all required elements, indicated with an asterisk (*) .
d.
511
d. Click Switch to XML View and specify the attribute for the <initial-command> and the <cli-tunnel-properties> element, which are not in the form view: i. On the warning message that appears, click Switch View. ii. In the Properties text box, use XML format to enter the the attribute and elements not available as fields in the form view. iii. Click OK. The newly configured adapter is now listed in the Adapters on Grid list. 7. (optional) Configure the adapter in the XML view: a. Enter BladeLogic Adapter as the adapter name. This is the default adapter name used by the processes in the BMC_BladeLogic-AD-Operations_Manager module. b. Enter a description for the adapter. c. Click Switch to XML View. d. On the warning message that appears, click Switch View. 8. In Properties, type the adapter configuration properties in an XML format, including the elements that are not available in the form view. The Properties text box must contain a valid XML configuration node for the adapter, as shown in Adapter configuration samples and elements . These samples show all possible elements. Note Do not include empty elements in the XML configuration. 9. Click OK to save the changes. A confirmation message is displayed on the Adapters page and the newly configured adapter is now listed in the Adapters on Grid list.
Adapter configuration samples and elements

BMC BladeLogic Server Automation versions 7.4 and later support SSO authentication with Secure Remote Protocol (SRP) and with Microsoft Active Directory and Kerberos. The adapter supports the following types of authentication: Authentication based on SRP that uses the user_info.dat file or the user name and password The BladeLogic Web Services interface (CLI tunnel) supports authentication based on SRP and is supported only with BMC BladeLogic Server Automation version 8.1. Authentication based on Microsoft Active Directory and Kerberos
Sample adapter configuration with SRP
The figure shows a sample configuration for both SRP-based authentication with srp-user-name and srp-password. In this sample, the adapter internally executes the blcred command:
blcred cred -acquire -profile defaultProfile -username username -password password
The blcred command acquires credentials and refreshes at intervals, based on the value of the <blsso-cache-refresh-interval> element in the adapter configuration. The following sample shows an adapter configuration with SRP and the adapter configured to interact with BMC BladeLogic Server Automation using the BladeLogic Web Services interface.
512
<config> <initial-command> <command prompt="%">nsh</command> </initial-command> <prompt>%</prompt> <authentication-mechanism>SRP</authentication-mechanism> <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.1\NSH\bin</executable-directory> <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory> <script-executable>nsh.exe</script-executable> <jython-executable>bljython.bat</jython-executable> <default-user-role>Admins</default-user-role> <profile-name>defaultProfile</profile-name> <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval> <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-interval-in-minutes> <install-certificate>yes</install-certificate> <install-certificate-prompt>?[yes|no]:</install-certificate-prompt> <blcli-jvm-options>-Xmx512M -XX:-HeapDumpOnOutOfMemoryError -Xms512m</blcli-jvm-options> <srp-user-name>Admin</srp-user-name> <srp-password>Admin</srp-password> <connection-ttl>30</connection-ttl> <timeout-secs>120</timeout-secs> <is-cli-tunnel-enabled>true</is-cli-tunnel-enabled> <cli-tunnel-properties> <application-server>blappserver</application-server> <web-service-port>9843</web-service-port> <user-name>Admin</user-name> <password>pass</password> <role-name>RBACAdmins</role-name> <session-refresh-interval>6</session-refresh-interval> </cli-tunnel-properties> </config>
The following configuration snippet shows a sample configuration for SRP-based authentication using the user credentials in the user_info.dat file. In this sample, the adapter internally executes the following command to acquire credentials:
blcred cred -acquire -profile defaultProfile -i "C:\Documents and Settings\kinituser\Application Data\BladeLogic\user\user_info.dat"
513
<config> <initial-command> <command prompt="%">nsh</command> </initial-command> <prompt>%</prompt> <authentication-mechanism>SRP</authentication-mechanism> <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.0\NSH\bin</executable-directory> <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory> <script-executable>nsh.exe</script-executable> <jython-executable>bljython.bat</jython-executable> <default-user-role>Admins</default-user-role> <profile-name>defaultProfile</profile-name> <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval> <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-interval-in-minutes> <install-certificate>yes</install-certificate> <install-certificate-prompt>?[yes|no]:</install-certificate-prompt> <blcli-jvm-options>-Xmx512M -XX:-HeapDumpOnOutOfMemoryError -Xms512m</blcli-jvm-options> <user-credential-file>C:\Documents and Settings\kinituser\Application Data\BladeLogic\user\user_info.dat</user-credential-file> <connection-ttl>30</connection-ttl> <timeout-secs>120</timeout-secs> <is-cli-tunnel-enabled>false</is-cli-tunnel-enabled> </config>
Sample adapter configuration with Active Directory and Kerberos
This sample code illustrates a configuration with Active Directory and Kerberos authentication. In this sample, the adapter internally executes the following command to acquire the credentials.
blcred cred -acquire -profile name
The adapter refreshes the credentials according to the value specified in the <blsso-cache-refresh-interval> element.
514
<config> <initial-command> <command prompt="%">nsh</command> </initial-command> <prompt>%</prompt> <authentication-mechanism>AD_KERBEROS</authentication-mechanism> <executable-directory>C:\Program Files\BMC Software\BladeLogic\8.0\NSH\bin</executable-directory> <script-directory>C:\scripts\BLOM\jy_Scripts</script-directory> <script-executable>nsh.exe</script-executable> <jython-executable>bljython.bat</jython-executable> <default-user-role>Admins</default-user-role> <profile-name>AD</profile-name> <blsso-cache-refresh-interval>1.5</blsso-cache-refresh-interval> <blsso-cache-recovery-interval-in-minutes>10</blsso-cache-recovery-interval-in-minutes> <install-certificate>yes</install-certificate> <install-certificate-prompt>?[yes|no]:</install-certificate-prompt> <connection-ttl>30</connection-ttl> <timeout-secs>120</timeout-secs> <is-cli-tunnel-enabled>false</is-cli-tunnel-enabled> </config>
Adapter configuration elements
The following table describes the configuration elements for both the SRP and Active Directory and Kerberos authentication.
Adapter configuration elements for SSO authentication
UI Label Executable Directory
Element <executable-directory>
Description Specifies the directory path containing the BMC BladeLogic executables: nsh, BLCLI, and bljython This path depends on the version of BMC BladeLogic: version 8.x = BL_HOME\NSH\bin version 7.x = BL_HOME\OM\bin
Required Yes
Script Directory
<script-directory>
Specifies the directory path containing the BLCLI wrapper scripts The support script types are nsh, sh, bat, and jy. Do not include spaces in the path.
Yes
515
Initial Command
<initial-command>
Specifies the initial command To use sessions and BMC BladeLogic SSO, you must specify the following initial command in the XML view for configuration: <command prompt="hostname%">nsh</command>
Yes
Prompt
<prompt>
Specifies the prompt to use for session capability You must specify a unique value for the prompt. Example: <hostname>% (Windows) or <hostname># (Linux)
Yes
Authentication <authentication-mechanism> Mechanism
Specifies the authentication mechanism to use for acquiring BMC BladeLogic SSO credentials The supported values are SRP and AD_KERBEROS
Yes
Profile Name SRP User Name SRP Password User Credential File
<profile-name> <srp-user-name>
Specifies the profile name for which to acquire the SSO ticket Specifies the user name used to acquire SSO credentials for SRP-based authentication Specifies the password used to acquire SSO credentials for SRP-based authentication Specifies the user information certificate or data file to use for SRP-based authentication If you do not specify the srp-user-name and srp-password for SRP authentication, specify the location of the file to acquire session credentials.
Yes Conditional
<srp-password>
Conditional
<user-credential-file>
Conditional
Script Executable
<script-executable>
Specifies the executable to run blcli, nsh, sh, and bat scripts Default value: nsh
No
Jython Executable
<jython-executable>
Specifies the executable to run Jython based scripts Default value: bljython
No
Default User Role
<default-user-role>
Specifies the role this user is performing You can override this value in the adapter request.
No
516
Credential Cache File
<credential-cache-file>
Specifies the file where the credential cache will be stored By default, BMC BladeLogic Server Automation stores the file in the user's home directory. For the example with kinituser, the file is stored in the C:\Documents and Settings\kinituser\Application Data\BladeLogic folder and the credential file is bl_sesscc.
No
Authentication <authentication-profile-file> Profile File
Specifies the authentication file used for the BMC BladeLogic Server Automation SSO By default, the BL_HOME /OM/br/authenticationProfiles.xml file is used. If you have a non-default authentication profile file, you must specify the location of the file in this element.
No
Trusted Keystore File
<trusted-keystore-file>
Specifies the keystore file By default, BMC BladeLogic Server Automation uses the home directory to search for the trusted keystore file. If you have a non-default location for certificates, you must specify the location in this element.
No
Blsso Cache Refresh Interval
<blsso-cache-refresh-interval> Specifies the interval, in hours, to refresh the SSO credentials By default, the adapter uses a value of 9 hours to refresh the credentials. You can also specify decimal values for the interval.
No
Blsso Cache Refresh Interval In Minutes
<blssocache-recoveryinterval-in-minutes>
Specifies the interval, in minutes, to recover the state of the adapter By default, the adapter uses a value of 5 minutes to recover the state of the adapter.
No
The adapter tries to recover the state of the adapter from the FAULT state to the RUNNING state indefinitely at the specified interval. Install Certificate <install-certificate> Specifies whether the adapter should install a BMC BladeLogic certificate, if the certificate is expired or not found Valid values: yes (default), no No
517
Install Certificate Prompt
<install-certificate-prompt>
Specifies the console prompt that is displayed when the BMC BladeLogic system is waiting for user input to determine whether to accept the certificate Valid values: ?[yes|no]:
No
Blcli Jvm Options
<blcli-jvm-options>
Sets the Java virtual machine (JVM) options to allocate memory in the BMC BladeLogic client The memory is allocated before any call to blcli_init, blcli_connect, or blcli_execute is executed. For example: If this element is set to Xmx512M, the max heap size is set to 512 MB before the JVM is created.
No
Login Conf File
<login-conffile>
Specifies the login configuration file used to acquire the SSO credential for Active Directory and Kerberos based authentication By default, BMC BladeLogic Server Automation uses the settings specified in the config.properties file.
No
Krb5 Conf File
<krb5-conffile>
Specifies the krb5 configuration file used to No acquire the SSO credentials for Active Directory and Kerberos based authentication By default, BMC BladeLogic Server Automation uses the settings specified in the config.properties file.
Connection Ttl
<connection-ttl>
Specifies the lifetime of the cached connections (or the NSH process), in seconds Default value: 60 seconds
No
Timeout Secs
<timeout-secs>
Specifies the timeout interval for command execution in seconds Default value: 60 seconds
No
Is CLI Tunnel Enabled
<is-cli-tunnel-enabled>
Specifies whether the CLI requests must No be processed through the BMC BladeLogic Web Services interface. Valid values: true, false (default)
<cli-tunnel-properties>
Contains the properties specific to the CLI tunnel
Conditional Required if the <is-cli-tunnel-enabled> element is set to true
518
<application-server>
Specifies the name of the BMC BladeLogic Application Server hosting the web service
<web-service-port>
Specifies the port number on which the BMC BladeLogic web service is running on the BMC BladeLogic Application Server The default value is 9843.
No.
<user-name>
Specifies the user name for authentication on the BMC BladeLogic Application Server
<password>
Specifies the password corresponding to the user name
<role-name>
Specifies the role that the current user would assume Default role: BLAdmins
No
<session-refresh-interval>
Specifies the interval, in minutes, at which the session ID required by the BMC BladeLogic Application Server is refreshed Valid value: integer. Default value: 5 minutes. The requests using BMC BladeLogic Web Services requires the session ID, and the session ID must be refreshed at regular intervals to ensure that the requests remain valid on the BMC BladeLogic Application Server.
No
The <is-cli-tunnel-enabled> element and its children elements are valid for BMC BladeLogic Server Automation version 8.1 only. For configuring the adapter with BMC BladeLogic Server Automation versions earlier than 8.1, you must set the <is-cli-tunnel-enabled> element to false.
Setting up authentication for BMC BladeLogic SSO

This section provides detailed setup instructions required for BMC BladeLogic SSO and the settings for the adapter. The BMC BladeLogic SSO feature has the following types of authentication: Active Directory and Kerberos SRP using user name and password SRP using credentials specified in the user_info.dat file By default, the SRP based SSO feature is enabled on BMC BladeLogic Server Automation. If you need to use Active Directory and Kerberos for authentication, you must configure BMC BladeLogic Server Automation from the
519
instructions in the "Implementing BladeLogic Active Directory/Kerberos Solution" section of the BMC BladeLogic Administration Guide. In addition, the following setup instructions differ from the BMC BladeLogic Administration Guide and are necessary to ensure that the feature works correctly. The BMC BladeLogic Administration Guide contains instructions for a user called blauthsvc. The BMC BladeLogic Administration Guide does not contain a reference for a user who actually acts as a client and logs in to the BMC BladeLogic Server Automation using Active Directory and Kerberos. The following instructions for the application adapter are for two users, blauthsvc and kinituser. Both of these users are Active Directory users and have two specific properties enabled in Active Directory: The password does not expire Data Encryption Standard (DES) encryption is enabled. In the following instructions, the blappserv_login.conf and blappserv_krb5.conf files apply to the user blauthsvc, and the blappclient_login.conf and blappclient_krb5.conf files apply to kinituser. To set up Active Directory and Kerberos for BMC BladeLogic SSO in BMC BladeLogic Server Automation You must set up the blclient_login.conf file as displayed in the following code snippet:
com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required doNotPrompt=true debug=true useKeyTab=true keyTab="C:\\Documents and Settings\\kinituser\\kinituser.keytab" principal="kinituser@BMC.COM";
The following steps and example demonstrate how to set up BMC BladeLogic SSO for a user called kinituser. 1. To generate the keytab file for kinituser, use the following command and adjust the element values based on your configuration: 2. C:\Documents and Settings\kinituser>ktpass \-out kinituser.keytab \-princ kinituser@BMC.COM \-mapuser kinituser@BMC.COM \-pass passw0rd# \-ptype KRB5_NT_PRINCIPAL \-crypto DES-CBC-MD5 Element Description
kinituser.keytab Specifies the output file name -princ Specifies the principal user name with domain The domain name must be capitalized. -mapuser -pass Specifies the map user name with domain The domain names must be in capitalized. Specifies the user password
The command generates the following warning, which you can ignore:
520
Targeting domain controller: S-17abd.BMC.com Using legacy password setting method }} Failed to set property "servicePrincipalName" to "kinituser" on Dn "CN=kinituser, CN=Users,DC=BMC,DC=com": 0x13. WARNING: Unable to set SPN mapping data. If kinituser already has an SPN mapping installed for kinituser, this is no cause for concern. Key created. Output keytab to kinituser.keytab: Keytab version: 0x502 keysize 47 kinituser@BMC.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 5 etype 0x3 (DES-CBC-MD5) keylength 8 (0x58a2b043e3bc91e0)
3. Create corresponding users in the BMC BladeLogic Server Automation database by using the Configuration Manager console. 4. You can verify the Active Directory and Kerberos configuration by performing either one of the following steps: a. Using the command line Execute the following command, where the username and password are for the kinituser created using the instructions in the earlier section.
C:\Documents and Settings\kinituser>blcred cred \-acquire \-profile AD Debug is true storeKey false useTicketCache true useKeyTab false doNotPrompt true ticketCache is C:\Documents and Settings\kinituser\krb5cc_kinituser KeyTab is null refreshKrb5Config is false principal is null tryFirstPass is false useFirstPass is false storePass is false clearPass is false Acquire TGT from Cache Principal is kinituser@BMC.COM Commit Succeeded Authentication succeeded: acquired session credential
b. Using the BMC BladeLogic Configuration Manager Console Log on to the BMC BladeLogic Configuration Manager Console using the Active Directory and Kerberos profile. If the logon is successful with either of these methods, the Active Directory and Kerberos authentication is verified and is ready to be used with the adapter. After logging on, the session credentials are generated by default in your home directory. Note For the example with kinituser, the default location of session credentials is C:\Documents and Settings\kinituser\Application Data\BladeLogic and the credential file is bl_sesscc.
To set up BMC BladeLogic SSO peers in BMC Atrium Orchestrator
For the BMC BladeLogic Server Automation adapter to function properly, you must perform the following steps: 1. On the peer on which the adapter is enabled, navigate to Control Panel => Administrative Tools => Services. 2. In the Services window, right-click the BMC Atrium Orchestrator service and select Properties from the menu. 3. Click the Log On tab, and click the option for the account. 4.
521
4. Enter the user name and password for this service. Note To ensure that the BMC BladeLogic Server Automation adapter functions properly, you must use the same credentials that you used when configuring the adapter. For the example with kinituser, use kinituser to configure the adapter. 5. Click Apply and then click OK. 6. Restart the BMC Atrium Orchestrator service. Note For information about troubleshooting issues with configuring the adapter, see Troubleshooting the BMC BladeLogic Server Automation adapter.
522
Application adapter module for the BMC BladeLogic Server Automation adapter
Each command supported by the application adapter has a corresponding process in the adapter module. Top-level processes perform high-level functions and call specialized processes in subdirectories. Each subdirectory contains process directories that correspond to the namespace for that command. Setup Validation directory for BMC BladeLogic Server Automation adapter Version directories for the BMC BladeLogic Server Automation adapter Utilities directory for the BMC BladeLogic Server Automation adapter Working with the BMC BladeLogic Server Automation adapter module Executing NSH commands and scripts using the BMC BladeLogic Server Automation adapter Modifying the command timeout for the BMC BladeLogic Server Automation adapter
Setup Validation directory for BMC BladeLogic Server Automation adapter

The processes in the Setup Validation directory are examples of operations. A process is provided to test each supported method of executing commands in BMC BladeLogic Server Automation. The processes in the Setup Validation directory contain sample values for request elements. You can change these sample values to reflect the values in your environment.
Version directories for the BMC BladeLogic Server Automation adapter

The adapter module contains the following version-specific directories: v7.42 v7.43 v7.5 v7.6 v8.0 v8.1 These directories contain subdirectories, organized by namespace, that contain processes to execute BLCLI commands supported by BMC BladeLogic Server Automation. Note If a process for a specific command exists in two directories, you must use the relevant process in the directory for the later version. For example, if a process for a specific command exists in the v7.42 and v7.43 directories, you must use the relevant process in the v7.43 directory to interact with BMC BladeLogic Server Automation version 7.43.
Utilities directory for the BMC BladeLogic Server Automation adapter

The Utilities directory contains general processes that perform validation, error checking, and the low-level actions that are used by processes in the top-level and version directories.
Working with the BMC BladeLogic Server Automation adapter module

This section is an introduction for building workflows using your knowledge of the BMC BladeLogic Server Automation and BMC Atrium Orchestrator. It guides you through the steps for creating a new process. The process
523
incorporates multiple called processes and uses the Context Item mapping. Details are provided to assist you with determining input parameters and Context Item mapping. To successfully create a workflow, you must: have a working knowledge of BMC BladeLogic Server Automation have work experience with the BladeLogic Command Line Interface (BLCLI) have successfully completed training for BMC Atrium Orchestrator have successfully completed training for using the BMC Atrium Orchestrator Development Studio or have relevant work experience
How to create a BMC BladeLogic Deploy Job that deploys a BMC BladeLogic Package
A BMC BladeLogic Deploy Job is used to deploy one or more files, including software, stored in the BMC BladeLogic Server Automation Depot on one or more servers. Deploying multiple files requires the use of a BMC BladeLogic Package to collect those files and related changes for configuration objects, applications, and files. The deploy job uses the package to execute those changes on the target servers. The package is copied to the target servers, and the instruction-set that is built into the package is executed. To create a Deploy Job, you must know the ID of the folder in which you want to create the job and the database key (DBKey) of the BMC BladeLogic Package. A single workflow can be created to obtain the ID and DBKey and create the Deploy Job. Tip Help is available for the BMC BladeLogic command line interface in the BLCLI help section in the BladeLogic\OM\doc\help\cli folder on the BMC BladeLogic Server Automation server.
Using BMC Atrium Orchestrator Development studio to create a new module and a new process in the module
Note This procedure uses processes from the v7.42 directory. When building workflow in your environment, use processes from the appropriate version directory.
To obtain the ID
1. Create a called process: a. From the BMC_BladeLogic-AD-Operations_Manager module, choose v7.42=> JobGroup => Group Name to ID. b. Drag and drop the Call Process activity between Start and End activities, as shown in the following figure.
Tip To view the complete path of the called process, place your cursor over the Call Process activity. 2. Determine the required inputs for the called process: 3. Double-click the Group Name to ID called process to display the Property panel. Property panel for the JobGroup:Group Name to ID called process
524
BMC Atrium Orchestrator Application Adapters 20.11.02 3.
4. In the Call Process Input Mapping pane, review the values in the Output Name column. Write down all the output names that are required. In this example, groupName is the only output name that is required. 5. Click Cancel to close the Property panel. 6. Create an input parameter for the value to be mapped. a. Double-click on the Start activity to display the Property panel. b. Click Add to insert an Input Parameter entry. c. Double-click the field under the Input Parameter Name column and type groupName in the field. This name is displayed when the process is tested or executed. d. Double-click in the Context Name field to launch the Context Browser. e. Click Add Context to open the Create Context Data window. f. Type a name for this Context Item (for example groupName), and then click OK. g. In the Context Browser, double-click the newly created Context Item. The Context Item automatically populates the Property panel of the Start Activity. h. Click the check box in the Required? column, as shown in the following figure.
i. Click OK to save the input parameter. 7. Map the inputs on the called process: a. Double-click the Group Name to ID called process to display the Property panel. b. Double-click the Input Type column for the groupName row. c. From the Parameter type menu, select Context item. d. To launch the Context Browser, click the Context Browser symbol . e. In the Context Browser, double-click the groupName entry. f. Click OK to close the detail panel and display the Property panel. The groupName Context Item defined on the Start activity is now mapped to the groupName input for this called process. 1. Map the value returned for the ID to a Context Item: a. In the Call Process Output Mapping pane of the Property panel, double-click the Output Name column for the ID row to display the detail pane. b.
525
1. BMC Atrium Orchestrator Application Adapters 20.11.02
From the Parameter type menu, select Context item. Click the Context Browser symbol . Click Add Context to open the Create Context Data window. Type a name for this Context Item (for example ID), and then click OK. In the Context Browser, double-click the ID entry. Click OK to close the detail panel and display the Property panel. The ID value returned by this called process is now mapped to a Context Item. This Context Item can be used as an input for a subsequent called process in this workflow. h. Click OK to save the mappings. 2. Test the process and debug as required. For more information about these functions, see Called processes.
To obtain a database key (DBKey)
b. c. d. e. f. g.
1. Add a called process to the existing workflow: a. From the BMC_BladeLogic-AD-Operations_Manager module, choose v7.42 => BlPackage => Get DB Key by Group and Name. b. Drag the Call Process Activity to the right of the Group Name to ID called process. 2. Determine the required inputs for the called process: a. Double-click the Get DB Key by Group and Name called process to display the Property panel, as shown in the following figure:
526
Property panel for the BLPackage:Get DBKey by Group and Name
1.
a. In the Call Process Input Mapping pane, review the values in the Output Name column. Write down all the output names that are required. In this example, parentGroup and packageName are the only output names that are required. b. Define these inputs using the method described in step 3 in the previous procedure. 2. Map the required inputs on the Get DBKey by Group and Name called process using the method described in the previous procedure. 3. Map the value returned for the DBKey to a Context Item: a. In the Call Process Output Mapping pane, double-click the Output Name column for the DBKey row to display the detail pane. b. Use the method described in Step 5 in the previous procedure. The Property panel for Get DB Key by Group and Name contains mappings.
Call Process Output Mapping pane for the BLPackage:Get DB Key by Group and Name called process
Click OK to save the mappings and test the process and debug, as required.
527
To create and deploy a job using the ID and DBKey
1. Add a called process to the existing workflow: a. From the BMC_BladeLogic-AD-Operations_Manager module, choose v7.42 => DeployJob => Create Deploy Job. b. Drag the Call Process activity to the workflow. 2. Determine the required inputs for the called process: a. Double-click the Create Deploy Job called process to display the Property panel, as shown in the following figure:
Property panel for the Create Deploy Job called process
1.
a. Use the method described in Obtaining the ID to define the following inputs on the Start activity: deployJob Name serverName isSimulateEnabled isCommitEnabled isStagedIndirect 2. Map the inputs using the method described in Obtaining the ID. These mappings uses Context Items defined on the Start activity and Context Items mapped to values for the ID and DBKey in the preceding called processes.
528
3. Test the process and debug as required. Your completed process should contain the called processes as illustrated in the following figure:
Sample process to deploy a job
Executing NSH commands and scripts using the BMC BladeLogic Server Automation adapter
The BMC BladeLogic Server Automation adapter can execute NSH commands and NSH scripts using the following mechanisms: NSH command using the adapter module NSH scripts using the <script-directory> element specified in the adapter configuration NSH scripts using the <script-directory> element specified in the adapter request, that overrides the value of the <script-directory> element in the adapter configuration
Executing NSH commands using the adapter module

For executing NSH commands using the adapter module, you must specify the connection details for the adapter without including a value for the <script-directory> element. The following code snippet illustrates the <connection-details> element without a value for the <script-directory> element.
... <connection-details> <script-directory/> <connection-details> ...
Executing NSH scripts using the <script-directory> element in the configuration

For executing NSH scripts with the value of the <script-directory> element specified in the adapter configuration, you must set the value of <script-directory> to USE_ADAPTER_CONFIG in the connection details for the adapter. The following code snippet illustrates the <connection-details> element that uses the value of the <script-directory> element in the adapter configuration.
.... <connection-details> <script-directory>USE_ADAPTER_CONFIG</script-directory> <connection-details> ....
529
Executing NSH scripts using the <script-directory> element in the adapter request or connection details for the adapter module
For executing NSH scripts with the <script-directory> element specified in the adapter request, you must specify the <script-directory> element in connection details for the adapter. The following code snippet illustrates the <connection-details> element containing the value of the <script-directory> element.
.... <connection-details> <script-directory>C:\test</script-directory> <connection-details> ....
For more details about using NSH scripts and NSH commands with the BMC BladeLogic Server Automation adapter, see Actor adapter requests and responses for executing scripts and commands on NSH.
Modifying the command timeout for the BMC BladeLogic Server Automation adapter
The adapter module deals with command timeout in the following ways: 1. If a value for timeout is not specified in the connection details of a workflow, a default timeout value of 300 seconds is inserted in the adapter request. 2. If a value for timeout is specified in the connection details, the specified value is used for the timeout of the given commands. You can modify the timeout for commands by adding the <BladeLogicConnectionDetail> tag in the workflow. The following code snippet shows an XML sample with the connection details element.
..... ..... <BladeLogicConnectionDetail> <adapter-name>adapter1</adapter-name> <timeout>1800</timeout> </BladeLogicConnectionDetail> .....
Note In this sample, the command timeout is set to 1800 seconds.
Actor adapter requests and responses for the BMC BladeLogic Server Automation adapter
This section contains the following information: Supported adapter request formats for the BMC BladeLogic Server Automation adapter Actor adapter requests and responses for executing BLCLI commands Actor adapter requests and responses for executing scripts and commands on NSH
530
Actor adapter requests and responses for executing Jython scripts Actor adapter request and response with different command formats Actor adapter requests and responses using the BladeLogic Web Services interface
Supported adapter request formats for the BMC BladeLogic Server Automation adapter
The BMC BladeLogic Server Automation adapter supports three different request formats for executing: BLCLI commands scripts and command execution on NSH Jython scripts Note This version of the application adapter for BMC BladeLogic Server Automation was tested and certified to interact with BMC BladeLogic Server Automation versions 7.4.2, 7.4.3, 7.5, 7.6, 8.0, and 8.1. You can use the information in this chapter with the Call Adapter activity to create an adapter request with one of the three supported methods.
Actor adapter requests and responses for executing BLCLI commands

The following table describes the adapter request elements to execute BLCLI commands. To override the configuration properties in the adapter configuration, include the <user-role> element in the request.
Adapter request elements to execute BLCLI commands
Element <user-role>
Definition Specifies the user role for executing commands on the server hosting BMC BladeLogic Server Automation You can use this element to override the <default-user-role> element in the adapter configuration.
Required No
<command>
Contains the set of information required to execute a BLCLI command An attribute of executable-type with a value of cli is required for this element. You can use the timeout-secs attribute to specify the time duration, in seconds, for executing the command. The default value of the timeout-sec attribute is 60 seconds. You can use this element to override the <timeout-secs> element in the adapter configuration.
Yes
<namespace>
Specifies the BladeLogic namespace in which to execute the command
Yes Yes No No
<command-name> Contains the BLCLI command <arguments> <argument> Contains the argument elements Contains the arguments for the BLCLI command One or more argument elements may be included in the request, as required by the BLCLI command.
531
Consult the help files on the BMC BladeLogic server to determine the BLCLI command names and the required arguments for each command. The help files are located at: version 7.x: BL_HOME\OM\doc\help\cli version 8.x: BL_HOME\NSH\doc\help\cli
The following code snippet illustrates a sample adapter request for the BLCLI method with the printAllProperties command.
<bladelogic-request> <request-data> <user-role>BLAdmins</user-role> <command executable-type="cli" timeout-secs="30"> <namespace>Server</namespace> <command-name>printAllProperties</command-name> <arguments> <argument>192.168.0.10</argument> </arguments> </command> </request-data> </bladelogic-request>
Each adapter request returns a response with the results of the command execution. The contents of the output element contain the information returned by BMC BladeLogic Server Automation. The following code snippet shows the adapter response for the sample adapter request for the BLCLI.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows 2003</os-id> <os-version>5.2</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>blcli_execute Server printAllProperties 192.168.0.10</command> <line-count>52</line-count> <execution-milliseconds>7734</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">STATE = Enrolled</line> <line index="2">ON_EDGE = false</line>
532
<line index="3">REPEATER_STAGING_DIR = /tmp/stage</line> <line index="4">ROLE_CREATED = BLAdmins</line> <line index="5">HOSTIP_BITS = 00001010100000000111000010101010</line> <line index="6">OS_VERSION = 2003</line> <line index="7">USER_CREATED = bladeuser</line> <line index="8">OS_VENDOR = Microsoft</line> <line index="9">IP_ADDRESS = 8.128.112.170</line> <line index="10">STAGING_DIR = /temp/stage</line> <line index="11">SYSTEMROOT = /C/WINDOWS</line> <line index="12">DATE_MODIFIED = 2009-10-30 13:14:54</line> <line index="13">OS_PLATFORM = x86</line> <line index="14">IS_ONLINE = true</line> <line index="15">AGENT_STATUS = agent is alive</line> <line index="21">FQ_HOST = RnD-QA1.rndlabs.qa.com</line> <line index="16">MS_OFFICE_INSTALL_USERNAME = </line> <line index="17">HOST = vm1</line> <line index="18">REPEATER_MAX_CACHE_SIZE = 0</line> <line index="20">OS_RELEASE = 5.2</line> <line index="21">ROLE_MODIFIED = BLAdmins</line> <line index="22">AUTO_GENERATED = false</line> <line index="23">SUBNET_MASK = 255.255.240.0</line> <line index="24">NETWORK_ADDRESS = 10.128.112.0</line> <line index="25">OS_PATCHLEVEL = SP2</line> <line index="26">IS_REPEATER = true</line> <line index="27">RSCD_DIR = /C/Program Files/BMC BladeLogic/RSC</line> <line index="28">RSCD_VERSION = 7.5.0.264</line> <line index="29">OS = Windows</line> <line index="30">VM_WS_USERNAME = </line> <line index="31">BROKEN_OBJECT = false</line> <line index="32">USER_MODIFIED = bladeuser</line> <line index="33">BUILD_ENVIRONMENT = Windows2003-x86</line> <line index="34">DEPLOYPATH = </line> <line index="35">DATE_CREATED = 2009-10-30 13:14:54</line> <line index="36">VM_VIRTUAL_MACHINE = false</line> <line index="37">NAME = 192.168.0.10</line> <line index="38">IS_DEPLOYABLE = true</line> <line index="39">WINDIR = /C/WINDOWS</line> <line index="40">PUSH_ACL_NO_USERS_FLAG = true</line> </output> </command-output> </commands-output>
533
</target-output> </targets-output> </bladelogic-response>
The following code snippet illustrates a sample adapter request for executing the listAllServers BLCLI command without any arguments.
<bladelogic-request> <request-data> <command executable-type = "cli" timeout-secs = "30"> <namespace>Server</namespace> <command-name>listAllServers</command-name> </command> </request-data> </bladelogic-request>
534
The following code snippet shows the adapter response for the sample adapter request with the listAllServers command.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>blcli_execute Server listAllServers</command> <line-count>22</line-count> <execution-milliseconds>10982</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">vm-w23-abc1022</line> <line index="2">10.118.29.145</line> <line index="3">Sanity10</line> <line index="4">Sanity11</line> <line index="5">vm-w28-abc456</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
The following code snippet illustrates a sample adapter request for executing the groupNameToID BLCLI command.
<bladelogic-request> <request-data> <command executable-type="cli" timeout-secs="300"> <namespace>JobGroup</namespace> <command-name>groupNameToId</command-name> <arguments> <argument>"/AOTest"</argument> </arguments> </command> </request-data> </bladelogic-request>
The following code snippet shows the adapter response for the groupNametoId command.
535
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>blcli_execute JobGroup groupNameToId "/AOTest" <line-count>1</line-count> <execution-milliseconds>8741</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">2000004</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
</command>
536
Actor adapter requests and responses for executing scripts and commands on NSH
The following table describes the adapter request elements for executing scripts and commands on NSH.
Adapter request elements for executing scripts and commands on NSH
Element
Description
Required Yes
<commands> Contains one or more child command elements that define an NSH script executable An attribute of executable-type with a value of nsh is required for this element. The script file must exist on the peer where the adapter is enabled and the script must have executable permissions. <command> Specifies the command or script name along with any required arguments that you want to execute on NSH You can use the script-directory attribute of the <command> element to specify the directory path containing the script files. You can use this element to override the <script-directory> element in the adapter configuration. To execute any command on NSH, you must set this attribute to empty. For example,
< command script-directory="">
Yes
The following code sample shows a sample adapter request for executing scripts and commands on NSH.
<bladelogic-request> <request-data> <command executable-type="nsh" timeout-secs="60"> <command>nsh_script1.nsh</command> </command> <command executable-type="nsh" timeout-secs="60"> <command script-directory="C:\Scripts\">nsh_script2.nsh</command> </command> <command executable-type="nsh" timeout-secs="60"> <command script-directory="">hostname</command> </command> </request-data> </bladelogic-request>
537
The following code sample shows the adapter response for script and command execution on NSH.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows 2003</os-id> <os-version>5.2</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>/C/BladeLogic/8.0/jy_Scripts/nsh_script1.nsh</command> <line-count>9</line-count> <execution-milliseconds>406</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">s-17125:</line> <line index="2"> Agent Release : 7.4.3.1011</line> <line index="3"> Hostname : S-17125</line> <line index="4"> Operating System: WindowsNT 5.2</line><line index="5"> User Permissions: BLRD@BMC1->Anonymous:PrivilegeMapped (Identity via trust)</line> <line index="6"> Security : Protocol=5, Encryption=TLS1</line> <line index="7"> Host ID : D45412A6</line> <line index="8"> # of Processors : 1</line> <line index="9"> License Status : Licensed for NSH/CM</line> </output> </command-output> <command-output> <metadata> <command>/C/Scripts/nsh_script2.nsh</command> <line-count>3</line-count> <execution-milliseconds>42125</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">/cygdrive/c/WINDOWS/system32</line> <line index="2">nsh:cd:2: connection timed out:</line> <line index="3">/cygdrive/c/WINDOWS/system32</line> </output> </command-output> <command-output> <metadata> <command>hostname</command>
538
<line-count>1</line-count> <execution-milliseconds>188</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">global-rbsjn05o</line> </output> </command-output> </commands-output>
539
The following code sample illustrates a sample adapter request for executing the agentinfo command on NSH.
<bladelogic-request> <command executable-type="nsh" timeout-secs="300"> <command script-directory="">agentinfo machine1</command> </command> </bladelogic-request>
540
The following code sample shows the adapter response for the agentinfo command execution on NSH.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>agentinfo machine1</command> <line-count>8</line-count> <execution-milliseconds>3429</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">machine1:</line> <line index="2"> Agent Release : 8.0.0.393</line> <line index="3"> Hostname : PortQA1</line> <line index="4"> Operating System: WindowsNT 5.2</line> <line index="5"> User Permissions: BLRD@PORTQA1->Anonymous:PrivilegeMapped (Identity via trust)</line> <line index="6"> Security : Protocol=5, Encryption=TLS1</line> <line index="7"> Host ID : A0493522</line> <line index="8"> #</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
541
Actor adapter requests and responses for executing Jython scripts

The following table describes the adapter request elements for executing Jython scripts.
Adapter request elements for executing Jython scripts
Element
Definition
Required Yes
<command> Contains the name of the Jython script to execute An attribute of executable-type with a value of jython is required for this element. The script-directory attribute can be used to specify the directory path containing the Jython script files. You can also use this element to override the <script-directory> element in the adapter configuration. Do not include spaces in the script directory path. The script directory must exist on the peer where the adapter is enabled and the script must have executable permissions. <user-role> Specifies the user role for executing the Jython script This element can be used to override the <default-user-role> element in adapter configuration. The following figure shows a sample adapter request for executing a Jython script.
<bladelogic-request> <request-data> <command executable-type="jython">depotgrp_getdbkey_args.jy</command> </request-data> </bladelogic-request>
No
542
The following figure illustrates the adapter response for the Jython script.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows 2003</os-id> <os-version>5.2</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>C:\"Program Files"\BladeLogic\OM\bin\bljython.bat c:\demo\depotgrp_getdbkey_args.jy"</command> <line-count>1</line-count> <execution-milliseconds>4843</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">DBKey:SBLGroupKey:1000002</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
The following figure illustrates another sample adapter request for executing a Jython script.
<bladelogic-request> <command executable-type="jython" timeout-secs="300" script-directory="/data/">test.jy</command> </bladelogic-request>
543
The following figure shows the adapter response for the Jython script execution.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>/opt/bmc/BladeLogic/8.0/NSH/bin/bljython "/data1/test.jy"</command> <line-count>1</line-count> <execution-milliseconds>32</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">ASP2</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
544
Actor adapter request and response with different command formats

The following figure illustrates an adapter request that executes a BLCLI command, a script on NSH, and a Jython script.
<bladelogic-request> <request-data> <user-role>Admins</user-role> <command executable-type="nsh" timeout-secs= "60"> <command>nsh_script1.nsh</command> </command> <command executable-type="cli" timeout-secs="60"> <namespace>Server</namespace> <command-name>printAllProperties</command-name> <arguments> <argument>vm2</argument> </arguments> </command> <command executable-type="jython" timeout-secs="60">list-all-servers.jy</command> </request-data> </bladelogic-request>
The following figure illustrates the adapter response for the sample request that executes a BLCLI command, a script on NSH, and a Jython script.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>/data1/scripts/nsh_script1.nsh</command> <line-count>29</line-count> <execution-milliseconds>2363</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">HOSTNAME LOAD MEMORY SWAP PROCS TIME UPTIME</line> <line index="2">dev-orchestr 0.00 13% 5% 22 12:27 days 11:43:36</line>
545
<line index="3">vm1:</line> <line index="4"> Agent Release : 7.4.3.1011</line> <line index="5"> Hostname : vm1</line> <line index="6"> Operating System: Linux 2.6.9-67.ELsmp</line> <line index="7"> User Permissions: 0/0 (root/root)</line> <line index="8"> Security : Protocol=5, Encryption=TLS1</line> <line index="9"> Host ID : 7F0100</line> <line index="10"> # of Processors : 2</line> <line index="11"> License Status : Licensed for NSH/CM</line> <line index="12">/usr</line> <line index="13">total 665</line> <line index="14">drwxr-xr-x 7 root root 4096 Jan 10 2007 X11R6</line> <line index="15">drwxr-xr-x 2 root root 98304 Jun 04 12:47 bin</line> <line index="16">drwxr-xr-x 2 root root 4096 Aug 12 2004 etc</line> <line index="17">drwxr-xr-x 9 root root 4096 Apr 28 19:45 evolution28</line> <line index="18">drwxr-xr-x 2 root root 4096 Aug 12 2004 games</line> <line index="19">drwxr-xr-x 250 root root 20480 Apr 28 19:47 include</line> <line index="20">drwxr-xr-x 6 root root 4096 Sep 11 2007 kerberos</line> <line index="21">drwxr-xr-x 165 root root 135168 Jun 03 14:53 lib</line> <line index="22">drwxr-xr-x 16 root root 4096 Apr 28 19:46 libexec</line> <line index="23">drwxr-xr-x 11 root root 4096 Apr 28 19:34 local</line> <line index="24">drwxr-xr-x 4 root root 4096 Apr 28 19:41 src</line> rds19</command> <line index="25">lrwxrwxrwx 1 root root 10 Apr 28 19:34 tmp -> ../var/tmp</line> </output> </command-output> <command-output> <metadata> </command-output> <command-output> <metadata> <command>blcli_execute Server printAllProperties 10.10.75.128</command> <line-count>46</line-count> <execution-milliseconds>8843</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index = "1"></line> <line index = "2">STATE = Enrolled</line> <line index = "3">LAST_UPDATED_DATE = 2008-08-06 11:43:53</line>
546
<line <line <line <line <line /tmp/stage</line>
index index index index index
= = = = =
"4">ON_EDGE = false</line> "5">VM_HOST =</line> "6">REPEATER_NAME =</line> "7">OS_RELEASE = 5.2</line> "8">REPEATER_STAGING_DIR =
<line index = "9">AUTO_GENERATED = false</line> <line index = "10">ROLE_MODIFIED = blomdemo</line> <line index = "11">ROLE_CREATED = blomdemo</line> <line index = "12">SUBNET_MASK = 255.255.255.0</line> <line index = "13">HOSTIP_BITS = 00001010000010100100101110000000</line> <line index = "14">NETWORK_ADDRESS = 10.10.75.0</line> <line index = "15">OS_VERSION = 2003</line> <line index = "16">USER_CREATED = blomdemo</line> <line index = "17">OS_VENDOR = Microsoft</line> <line index = "18">OS_PATCHLEVEL = SP2</line> <line index = "19">IS_REPEATER = true</line> <line index = "20">RSCD_VERSION = 7.4.3.1011</line> <line index = "21">RSCD_DIR = /C/Program Files/BladeLogic/RSC</line> <line index = "22">IP_ADDRESS = 10.10.75.128</line> <line index = "23">DEPLOYNAME =</line> <line index = "24">VM_WS_USERNAME =</line> <line index = "25">OS = Windows</line> <line index = "26">USER_MODIFIED = blomdemo</line> <line index = "27">STAGING_DIR = /tmp/stage</line> <line index = "28">SYSTEMROOT = /C/WINDOWS</line> <line index = "29">DEPLOYPATH =</line> <line index = "30">CUSTOMER =</line> <line index = "31">DATE_MODIFIED = 2008-08-06 11:43:58</line> <line index = "32">DATE_CREATED = 2008-08-06 11:43:58</line> <line index = "33">AGENT_STATUS = agent is alive</line> <line index = "34">IS_ONLINE = true</line> <line index = "35">OS_PLATFORM = x86</line> <line index = "36">ROLLBACKPATH =</line> <line index = "37">FQ_HOST = India-Dev2</line> <line index = "38">VM_VIRTUAL_MACHINE = false</line> <line index = "39">VM_WS_PWD =</line> <line index = "40">NAME = 10.10.75.128</line> <line index = "41">DESCRIPTION = localhost</line> <line index = "42">WINDIR = /C/WINDOWS</line> <line index = "43">HOST = S-17125</line> <line index = "44">VM_WS_URL =</line> <line index = "45">REPEATER_MAX_CACHE_SIZE = 0</line> <line index = "46">PUSH_ACL_NO_USERS_FLAG = true</line> </output> </command-output> </command-output> <command-output> <metadata> <command>/C/"Program Files"/BladeLogic/OM/bin/bljython.bat "C:\User\BLOM\jy_Scripts\list-all-servers_remote_execution.jy"</command>
547
<line-count>30</line-count> <execution-milliseconds>3407</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index = "1">Traceback (innermost last):</line> <line index = "2">File "C:\jy_Scripts\list-all-servers_remote_execution.jy", line 23, in ?</line> <line index = "3">File "c:\Progra~1\BladeLogic\OM\br\jython\bladelogic\cli\CLI.py", line 100, in connect</line> <line index = "5">at com.bladelogic.cli.CLIMain.getSessionCredentialFromCache(CLIMain.java:1084) </line> <line index = "6">at com.bladelogic.cli.CLIMain.loginToAppServer(CLIMain.java:857) </line> <line index = "7">at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) </line> <line index = "8">at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) </line> <line index = "9">at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) </lin <line index = "10">at java.lang.reflect.Method.invoke(Method.java:585) </line> <line index = "11">at org.python.core.PyReflectedFunction.__call__(PyReflectedFunction.java) </line> <line index = "12">at org.python.core.PyMethod.__call__(PyMethod.java) </line> <line index = "13">at org.python.core.PyObject.__call__(PyObject.java) </line> <line index = "14">at org.python.core.PyInstance.invoke(PyInstance.java) </line> <line index = "15">at <line index = "26">at org.python.core.__builtin__.execfile_flags(__builtin__.java) </line> <line index = "27">at org.python.util.PythonInterpreter.execfile(PythonInterpreter.java) </line> <line index = "28">at org.python.util.jython.main(jython.java) </line> <line index = "29"></line> <line index = "30">com.bladelogic.cli.ConnectionException: com.bladelogic.cli.ConnectionException: no authentication profile name specified.</line> </output> </command-output> </commands-output>
548
Actor adapter requests and responses using the BladeLogic Web Services interface
You can use the BladeLogic Web Services interface for executing Command Line Interface (CLI) commands only. The BladeLogic Web Services interface cannot execute NSH scripts, NSH commands, or Jython scripts. The following code snippet illustrates a sample adapter request that uses the BladeLogic Web Services interface to execute the getAllRoleNames command, without any arguments.
<bladelogic-request> <command executable-type="cli">RBACRole getAllRoleNames</command> </bladelogic-request>
The following code snippet shows the adapter response for the request with the getAllRoleNames command.
<bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <commands-output> <command-output> <metadata> <command>RBACRole getAllRoleNames</command> <line-count>1</line-count> <execution-milliseconds>1281</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">[GlobalReportAdmins, GlobalReportViewers, RBACAdmins, BLAdmins]</line> </output> </command-output> </commands-output> </target-output> </targets-output> </bladelogic-response>
The following code snippet illustrates a sample adapter request that uses the BladeLogic Web Services interface to execute the printAllProperties BLCLI command with arguments.
549
<bladelogic-request> <request-data> <command executable-type="cli"> <namespace>Server</namespace> <command-name>printAllProperties</command-name> <arguments> <argument>vm-w23-abc60</argument> </arguments> </command> </request-data> </bladelogic-request>
The following code snippet illustrates the adapter response for the request with the printAllProperties command.
<adapter-response> <execution-duration>1609</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <bladelogic-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <commands-output> <command-output> <metadata> <command>Server printAllProperties vm-w23-abc60</command> <line-count>65</line-count> <execution-milliseconds>1609</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">OS_PLATFORM = x86</line> <line index="2">RSCD_VERSION = 8.1.0.113</line> <line index="3">REPEATER_MAX_CACHE_SIZE = 0</line> <line index="4">VM_WS_USERNAME = </line> <line index="5">BUILD_ENVIRONMENT = Windows2003-x86</line> <line index="6">USER_MODIFIED = BLAdmin</line> <line index="7">IS_REPEATER = true</line> <line index="8">MS_OFFICE_INSTALL_LOCATION = </line> <line index="9">NETWORK_ADDRESS = 10.128.28.0</line> <line index="10">HOST = vm-w23-abc60</line> <line index="11">DEPLOYNAME = </line> <line index="12">OS_VERSION = 2003</line> <line index="13">ROLLBACKPATH = </line> <line index="14">ROLE_CREATED = BLAdmins</line> <line index="15">AGENT_STATUS = agent is alive</line> <line index="16">VM_WS_URL = </line> <line index="17">DATE_MODIFIED = 2010/05/14 14:37:58+0530</line>
550
<line index="18">NAME = vm-w23-abc60</line> <line index="19">DESCRIPTION = </line> <line index="20">CUSTOM_OBJECTS_ENVIRONMENT* = </line> <line index="21">MS_OFFICE_INSTALL_PWD = </line> <line index="22">AGENT_MINOR_VERSION* = 1</line> <line index="23">AUTO_GENERATED = false</line> <line index="24">IS_DEPLOYABLE = true</line> <line index="25">VM_WS_PWD = </line> <line index="26">VM_VIRTUAL_MACHINE = false</line> <line index="27">AGENT_MAJOR_VERSION* = 8</line> <line index="28">DEPLOY_ALLOW_NFS_DURING_SUM = false</line> <line index="29">ROLE_MODIFIED = BLAdmins</line> <line index="30">PUSH_ACL_NO_USERS_FLAG = true</line> <line index="31">SOLARIS_ALTERNATIVE_BOOT_ENV* = </line> <line index="32">AGENT_BUILD_VERSION* = 113</line> <line index="33">FQ_HOST = vm-w23-abc60.labs.abc.com</line> <line index="34">DATE_CREATED = 2010/05/14 14:37:57+0530</line> <line index="35">WINDIR = /C/WINDOWS</line> <line index="36">STATE = Enrolled</line> <line index="37">OS_RELEASE = 5.2</line> <line index="38">REPEATER_NAME = </line> <line index="39">LAST_UPDATED_DATE = 2010/05/14 14:37:58+0530</line> <line index="40">USER_CREATED = BLAdmin</line> <line index="41">LIFECYCLE* = </line> <line index="42">OS_PATCHLEVEL = SP2</line> <line index="43">IS_SOLARIS_LIVE_UPGRADE* = false</line> <line index="44">IS_ONLINE = true</line> <line index="45">IS_VIRTUAL* = false</line> <line index="46">AGENT_PATCH_VERSION* = 0</line> <line index="47">VM_HOST = </line> <line index="48">OS_ENUMERATED_VALUE* = Windows</line> <line index="49">RSCD_DIR = /C/Program Files/BMC Software/BladeLogic/8.1/RSCD</line> <line index="50">STAGING_DIR = /temp/stage</line> <line index="51">IP_ADDRESS = 10.118.18.93</line> <line index="52">MS_OFFICE_INSTALL_USERNAME = </line> <line index="53">CUSTOMER = </line> <line index="54">TRANSACTIONS_DIR = </line> <line index="55">HOSTIP_BITS = 00001010100000000001110001100010</line> <line index="56">OS = Windows</line> <line index="57">REPEATER_STAGING_DIR = /tmp/stage</line> <line index="58">BROKEN_OBJECT = false</line> <line index="59">OS_VENDOR = Microsoft</line> <line index="60">SUBNET_MASK = 255.255.212.0</line> <line index="61">ON_EDGE = false</line> <line index="62">SYSTEMROOT = /C/WINDOWS</line> <line index="63">BL_ACL* = 356a870d-09e0-49f8-9814-b604281f3dde 1102 DBKey:SBlAclKeyImpl:2002000</line> <line index="64">VIRTUALIZATION* = </line> <line index="65">DEPLOYPATH = </line> </output> </command-output> </commands-output>
551
Troubleshooting the BMC BladeLogic Server Automation adapter

This section contains information about: Configuration errors Executing any operation in an Oracle Solaris environment creates a core dump file Persistent connections
Configuration errors
If you did not configure the file blclient_login.conf for BMC BladeLogic SSO, the following error is generated:
Acquire TGT from CacheCredentials are no longer validPrincipal is nullnull credentials from Ticket Cache Krb5LoginModule authentication failed Unable to obtain Princpal Name for authentication Cannot obtain user credential: GSSException: no valid credentials provided (Mechanism level: Attempt to obtain new INITIATE credentials failed\! (null))
If you receive the following error message, the Microsoft Active Directory user you attempted to authenticate is not present in the BMC BladeLogic Server Automation Console.
{{{}Acquire TGT from CacheCredentials are no longer validPrincipal is nullnull credentials from Ticket Cache Krb5LoginModule authentication failed Unable to obtain Princpal Name for authentication Cannot obtain user credential: GSSException: no valid credentials provided (Mechanism level: Attempt to obtain new INITIATE credentials failed\! (null))}}
Executing any operation in an Oracle Solaris environment creates a core dump file
If you get a core dump or a segmentation error while executing any operation with BMC BladeLogic Server Automation version 7.5 or later in an Oracle Solaris environment, you must ensure that BMC Atrium Orchestrator uses the same Java Virtual Machine (JVM) that is used by BLCLI. To enable BMC Atrium Orchestrator to use the same JVM as BLCLI 1. Navigate to the AO_HOME/bin/server.sh file on the peer where the adapter is enabled. 2. Edit the server.sh file to specify the BLJVM_PATH, below the line specifying the JAVA_HOME variable:
JAVA_HOME="/usr/jdk/jdk1.5.0_10" BLJVM_PATH=${JAVA_HOME}/jre/lib/sparc/server/libjvm.so export BLJVM_PATH
552
In this example, BLCLI uses Java located at /usr/jdk/jdk1.5.0_10.
Persistent connections
The BladeLogic adapter supports persistent connections to the BMC BladeLogic Server Automation. Persistent connections reuses an opened connection to serve multiple adapter requests rather than opening and closing a new connection for each adapter request, resulting in performance improvements for the adapter. The BladeLogic adapter can name and cache an opened connection (NSH process), based on the Job ID of the adapter request. All requests that share a common Job ID reuse the same cached NSH session rather than opening new NSH processes. For adapter requests with different Job IDs, different connections are established and cached.
Lifespan of a cached connection

Every cached connection has a corresponding time period during which the connection can be used and reused by adapter requests having the same Job ID. After this time period elapses, the cached connection is invalid and is removed from the cache. The lifetime of each cached-connection (NSH process) depends on the <ttl> value of adapter request (every adapter request contains the <ttl> value). Note If the adapter module is activated on the grid, you can use the Process timeout property of the workflow to set the <ttl> value of adapter request. An adapter request can take different values for the <ttl> element under the following scenarios: Irrespective of whether the Process timeout property is set or not, if a process is executed from the Development Studio, the adapter request uses a default <ttl> value of 15 seconds. If no value is set for the Process timeout property, and the adapter module is activated on the grid, the server sets a very high <ttl> value of 4611686018427387887 milliseconds for adapter requests. If a value is set for the Process timeout property and the adapter module is activated on the grid, the specified value is set as the <ttl> value of the adapter request. Note If a workflow is activated on the grid and the Process timeout property of the workflow is not set or is set to value greater than one hour (3600000ms), the adapter uses the value of the <connection-ttl> configuration element to set the lifetime of the cached connection. If no value or an invalid value is specified for <connection-ttl> in the adapter configuration, the adapter uses a default value of 60 seconds.
553
BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
Application adapters enable BMC Atrium Orchestrator workflow processes to perform specialized functions and to interact with external applications by providing an interface between the workflow processes and the external systems and applications. The BMC Atrium Orchestrator application adapter for BMC ProactiveNet Performance Manager interfaces with BMC ProactiveNet Performance Manager. The BMC Atrium Orchestrator application adapter for BMC ProactiveNet Performance Manager consists of an actor adapter, a monitor adapter, and workflow processes to perform the standard applications actions available through the BMC ProactiveNet Performance Manager API.
BMC Atrium Orchestrator actor adapter for BMC ProactiveNet Performance Manager
The actor adapter for BMC ProactiveNet Performance Manager performs the following operations on BMC Service Impact Manager (BMC SIM) cells: Creates, updates, retrieves, and annotates events Enables and disables the maintenance mode The adapter operations target BMC ProactiveNet Performance Manager cells. Each request to the adapter starts a sequence of requests and responses between the adapter and BMC ProactiveNet Performance Manager. When an adapter receives a request, the following sequence occurs: 1. The adapter looks up the IP address of the host cell in the mcell.dir file local to the BMC Atrium Orchestrator peer. For details about the mcell.dir file, see Communicating with a BMC ProactiveNet Performance Manager cell. 2. The adapter opens a client connection to the cell specified in the request or the default cell specified in the adapter configuration. 3. The adapter registers itself with the server by issuing a register request. 4. The BMC Impact Administration Server acknowledges the registration request. The adapter receives the acknowledgment asynchronously when the underlying API invokes the processAnswer() callback method. 5. The adapter sends the actual query request to the server. The server returns the response to the query with the processAnswer() callback method. 6. The adapter sends additional requests and operations, if required, and the server returns the responses to these requests with the same processAnswer() callback method. 7. The adapter closes and unregisters requests. The BMC ProactiveNet Performance Manager server acknowledges these requests. 8. The adapter closes the client connection. 9. The adapter collates all the responses from the server and returns the adapter response to the caller. 10. Adapter requests can target different BMC ProactiveNet Performance Manager cells. The adapter creates and closes a new connection for each request. 11. The adapter converts the requests into Basic Recorder of Objects in C (BAROC) formatted queries that a BMC ProactiveNet Performance Manager cell understands. Note The BAROC format is a proprietary BMC ProactiveNet Performance Manager query language.
Communicating with a BMC ProactiveNet Performance Manager cell

To communicate with a BMC ProactiveNet Performance Manager cell, the adapter's underlying APIs, IMAP, and
554
IMCOMM API require access to the mcell.dir file. The mcell.dir file for the BMC Event Manager application is located at installHome\pw\server\etc in the BMC Impact Administration Server installation directory. You can use the mcell.dir file on the application (BMC ProactiveNet Performance Manager) side as a reference to create or copy the mcell.dir file required by BMC Atrium Orchestrator, which is then placed on the BMC Atrium Orchestrator peer on which the adapter is enabled. The path to access this local file must be present in the adapter configuration. The mcell.dir file contains the following cell definitions: cell name host port encryption key host2 port2 Note The host2 and port2 fields in the mcell.dir file are used in high-availability setups for specifying secondary cells. If the cell name changes on the application (BMC ProactiveNet Performance Manager) side, you must make corresponding changes in the mcell.dir file in BEM and the copy of the mcell.dir file that is local to the BMC Atrium Orchestrator peer to ensure that the actor adapter continues to communicate with the cell. You must disable and re-enable the adapter after the changes are made to the mcell.dir file local to the BMC Atrium Orchestrator peer. In case you also use the monitor adapter and change the cell name on the application (BMC ProactiveNet Performance Manager) side, you must set up event monitoring for the new cell again as described in Setting up events for the BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager .
Supported versions of BMC ProactiveNet Performance Manager

The adapter supports versions 8.5 and 8.5.01 of BMC ProactiveNet Performance Manager.
Configuring the BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with BMC ProactiveNet Performance Manager. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes using XML only. However, after you switch to the XML view and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration. Note The default name for the actor adapter is BPPMActorAdapter.
555

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. Access the adapters page by clicking the Manage tab; then click the Adapters tab. 3. In the Adapters in Repository list: Select the bmc-adapter-bmc-proactivenet-performance-manager-actor check box to configure the actor adapter. Select the bmc-adapter-bmc-proactivenet-performance-manager-monitor check box to configure the monitor adapter. Select both check boxes to configure both adapters. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or skip to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. Note The Name field does not support single-quote (') and ampersand (&) characters. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements, indicated with an asterisk (*). 7. (optional) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements and attributes from the adapter user guide into the Properties text box, and then click OK. Note If the default value for an optional element is acceptable, omit the element. Do not include empty elements. e. On the Warning message that appears, click Save. This action saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the node elements required for configuring the actor adapter: Node elements for configuring the actor adapter UI label Mcell Dir File Path Element <mcell-dir-file-path> Description Specifies the location of the mcell.dir file local to the BMC Orchestrator peer on which the adapter is enabled The mcell.dir file contains information about the cell.
For details about the mcell.dir file, see BMC Atrium Orches actor adapter for BMC ProactiveNet Performance Manager
556
Cell Name
<cell-name>
Specifies the cell name in BMC ProactiveNet Performance where the events are reported
User Name
<user-name>
Specifies the user name used for authentication
Request Field Mapping File Location
<request-field-mapping-file-location> Specifies the location of the request field mapping file loc BMC Atrium Orchestrator peer
The request field mapping file contains information about such as custom slot name mapping, where you can specify names to be used in requests.
The slot names can be additional slots not incorporated ear existing slots that need to be identified with different names example, you can map an external name, MyMessage, to a corresponding internal name used by BMC ProactiveNet Performance Manager, msg, as follows:
<elements> <element> <external>MyMessage</external> <internal>msg</internal> </element> </elements>
If the external slot names for ID, Origin Time, Component ID Component Type, Status, Notes, Owner, or Priority are cha need to make corresponding changes in the adapter modul configuration to ensure that the wrapper validations work pr Config File Location <config-file-location>
Specifies the location of the mclient.conf file local to the B Orchestrator peer
You can use the mclient.conf file in the BMC Service Impa Manager server installation location as a reference to create the mclient.conf file required by BMC Atrium Orchestrator. mclient.conf file is then placed on the BMC Atrium Orches on which the adapter is enabled.
The mclient.conf file contains the information about the ce customized values for connection configuration parameters example, MessageBuffer parameters, Trace parameters, an
For details about the .conf files, see the BMC ProactiveNet Administrator Guide available at https://docs.bmc.com/docs/display/bppmsuite86/PDF+prod .
557
Component Name
<component-name>
Specifies the component name used for maintenance mode
<max-active-connections> Max Active Connections
Specifies the number of simultaneous active connections th made to a particular cell
If you specify a negative value, the number of simultaneous connections that can be made is unlimited. Default value: 8 <min-active-connections> Min Active Connections
Specifies the minimum number of connections that are alwa present in the connections pool
You can use this element to optimize the number of active connections in the pool, which is required to make buffering Default value: 0 The following figure shows an XML sample for configuring the actor adapter. XML sample for configuring the actor adapter
<config> <mcell-dir-file-path>/xyz/abc/lmn/mcell.dir</mcell-dir-file-path> <cell-name >somecell</cell-name> <user-name>someuser</user-name> <request-field-mapping-file-location>/xyz/abc/lmn/mymapping.xml </request-field-mapping-file-location> <config-file-location>/xyz/abc/lmn/mcell.conf</config-file-location> <component-name>test</component-name> </config>
The following table describes the node elements required for configuring the monitor adapter: Node elements for configuring the monitor adapter UI label Port Gateway Name Element <port> <gateway-name> Description Specifies the port on which the gateway listens Specifies the name of the gateway Required Yes No
Encryption Key <encryption-key> Specifies the encryption key used to encrypt events Yes
Note The configuration information that you specify for the monitor adapter must match that specified in the incomm.conf and mcell.dir files located on the BMC ProactiveNet Performance Manager server. The following figure shows an XML sample for configuring the monitor adapter. XML sample for configuring the monitor adapter
558
<config> <port>1859</port> <gateway-name>BPPMGW</gateway-name> <encryption-key>mc</encryption-key> </config>
BMC ProactiveNet Performance Manager application adapter module

SetupValidation directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The processes in the SetupValidation directory contain sample values for request elements. These sample values can be quickly changed to reflect the values in your environment. A process is provided to test each supported method of executing operations in BMC ProactiveNet Performance Manager.
Version directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The v8.5 directory contain functional processes specific to a version of BMC ProactiveNet Performance Manager. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of the operation. In the v8.5 directory, the functional processes are specific to 8.5 and 8.5.01. The following table maps the version directory information with BMC ProactiveNet Performance Manager versions. Mapping of version directory information with BMC ProactiveNet Performance Manager versions Version directory Compatible with BMC ProactiveNet Compatible with BMC ProactiveNet Performance Manager 8.5? Performance Manager 8.5.01? v8.5 Yes Yes
Top-level processes for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The top-level processes perform high-level operations and call specialized processes in the subdirectories of the v8.5 directory. The top-level processes in the Project Explorer window execute the following version-specific processes. Create Items Find Items Perform Operations Update Items
559
Create Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Create Items process enables you to create one or more events based on the information specified in the request. The valid value for <item type> is event. The following figure shows a sample <items> XML element for the Create Items process. <items> XML element for the Create Items process
<items> <item> <connection-parameters> <user-name>user</user-name> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Message</name> <value>TINIMaINI</value> </argument> <argument> <name>Category</name> <value>OPERATIONS_MANAGEMENT</value> </argument> <argument> <name>Severity</name> <value>info</value> </argument> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Host</name> <value>s-17124</value> </argument> <argument> <name>Component ID</name> <value>EM_Cell_Server -Dev1</value> </argument> <argument> <name>Rule</name> <value>testMCTOOLRULE</value> </argument> <argument> <name>Class</name> <value>MC_CELL_PARSE_ERROR</value> </argument> <argument> <name>Account</name> <value>testaccount</value>
560
</argument> <argument> <name>Object Class</name> <value>testobjclass</value> </argument> <argument> <name>Parameter</name> <value>testparameter</value> </argument> <argument> <name>Object</name> <value>testobject</value> </argument> <argument> <name>Parameter Threshold</name> <value>testParameterThreshold</value> </argument> <argument> <name>SMC Alias</name> <value>EM_Cell_Server_1_India-Dev1</value> </argument>
561
Find Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Find Items process enables you to retrieve the events matching the search criteria specified in the request. The Find Items process can perform the following activities: Retrieve Event by Date Retrieve Events by Component Retrieve Events by ID Retrieve Events The valid values for <item type> are: date component ID retrieve The following figure shows a sample <items> XML element for the Find Items process. <items> XML element for the Find Items process
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component Type</name> <value>BMC_AdministrationApplication</value> </argument> <argument> <name>Class</name> <value>EVENT</value> </argument> </arguments> </item> </items>
Note You can retrieve events by specifying the event class, EVENT specified in the Find Items request as shown in the preceding figure. If you do not specify a class, all the events corresponding to all the classes are retrieved. For example, if you specify the event class as EVENT, the Find Items process retrieves events of the EVENT event class. It does not retrieve events in subclasses of EVENT.
562
Perform Operations process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Perform Operations process performs the following maintenance mode operations on the specified components: Disable Event Reporting Resume Event Reporting The valid values for <item type> are disable-event-reporting and resume-event-reporting. The following figure shows a sample <items> XML element for the Perform Operations process. <items> XML element for the Perform Operations process
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell - ESG1</component-name> </item> </items>
Update Items process for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Update Items process enables you to retrieve the events matching the search criteria and update the events using the values specified in the request. The Update Items process can perform the following activities: Acknowledge Event Annotate Event Assign Event Close Event Reopen Event Set Action Result Set Event Priority Update Event The valid values for <item type> are: acknowledge annotate assign close reopen set action result prioritize update The following figure shows a sample <items> XML element for the Update Items process. <items> XML element for the Update Items process
563
{<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component Type</name> <value>BMC_AdministrationApplication</value> </argument> </arguments> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>message text</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> </item> </items>
Process inputs for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The following table describes the input elements used by a process in the adapter module.
Process input elements Element <adapter name> Description Specifies the name of the adapter that handles the request Required Conditional; not required if the adapter is enabled using the default adapter name Yes Yes
<items> <item type>
Contains the <item> XML elements used to execute the events Specifies the type of process that must be executed
564
<version> Specifies the version directory from which the process should be executed See Mapping of version directory information with BMC ProactiveNet Performance Manager versions for information about compatibility of processes in the v8.5 directory with BMC ProactiveNet Performance Manager versions. Valid values: 8.5
Yes
Utilities directory for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Utilities directory contains constructor processes that you can use to create the complex XML inputs required in the functional version-specific processes. The constructor processes are organized into general utilities and subdirectories that correspond to the supported operation types.
Actor adapter requests and responses for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The actor adapter can perform different API calls on BMC ProactiveNet Performance Manager. The adapter requests contain values that are used to execute API calls. The set of values used to make each API call is referred to as an operation. The available operations for the actor adapter are: Create Event Maintenance mode operations Retrieve Event Update Event You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity.
Adapter request and response for the Create operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
This section illustrates the adapter request and response for the Create Event operation and describes the elements used in the request. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Create Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Create Event operation enables you to create events based on the information specified in the request. The following figure shows a sample <items> XML element for the Create Event operation. Sample <items> XML element for the Create Event operation
565
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name></name> <value></value> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Create Event operation. Adapter request for the Create Event operation
<<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <operation-name>create-event</operation-name> <arguments> <argument> <name>Message</name> <value>TIKOPsIKO1</value> </argument> <argument> <name>Category</name> <value>OPERATIONS_MANAGEMENT</value> </argument> <argument> <name>Severity</name> <value>info</value> </argument> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Host</name> <value>s-17124</value> </argument> <argument> <name>Component ID</name> <value>EM_Cell_Server_1-Dev1</value> </argument>
566
<argument> <name>Rule</name> <value>testMCTOOLRULE</value> </argument> <argument> <name>Class</name> <value>MC_CELL_PARSE_ERROR</value> </argument> <argument> <name>Account</name> <value>testaccount</value> </argument> <argument> <name>Object Class</name> <value>testobjclass</value> </argument> <argument> <name>Parameter</name> <value>testparameter</value> </argument> <argument> <name>Object</name> <value>testobject</value> </argument> <argument> <name>Parameter Threshold</name> <value>testParameterThreshold</value> </argument> <argument> <name>SMC Alias</name> <value>EM_Cell_Server_1_India-Dev1</value>
567
</argument> </arguments> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Create Event operation. Adapter response for the sample Create Event operation
568
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-response> <Modified>1205224197</Modified> <Status>OPEN</Status> <Severity>INFO</Severity> <Owner></Owner> <Component_ID>EM_Cell_Server_1-Dev1</Component_ID> <Host>s-17124</Host> <Origin_Time>0</Origin_Time> <Message>TIKOPsIKO1</Message> <Priority>PRIORITY_2</Priority> <Time_To_Close>0</Time_To_Close> <Component_Type></Component_Type> <Service></Service> <Received>1205224197</Received> <Occurances>0</Occurances> <Arrived>1205224197</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1205224197</Occurred> <Host_Address></Host_Address> <Location>Unknown</Location> <ID>mc.1828.1210339483775</ID> <Class>MC_CELL_PARSE_ERROR</Class> <mc-tool>bppm-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmceventmanageractoradapter </mc-tool-address> <Rule>testMCTOOLRULE</Rule> <mc-tool-time>1214236542</mc-tool-time> <Account>testAccount</Account> <Object_Class>testObjectClass</Object_Class> <Parameter>testParameter</Parameter> <Object>testObject</Object> <Parameter_Threshold>testParameterThreshold</Parameter_Threshold> <SMC_Alias>EM_Cell_Server_1_India-Dev1</SMC_Alias> </query-response> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Adapter requests and responses for the Maintenance Mode operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
This section illustrates the adapter requests and responses for the following Maintenance Mode operations and
569
describes the elements used in the requests: Disable Event Reporting Resume Event Reporting Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Disable Event Reporting operation

The Disable Reporting operation enables you to disable reporting on a cell specified in the request. Note This operation requires propagation rules to be set in BMC ProactiveNet Performance Manager. For more information, see Propagation rules for maintenance mode for BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager. The following figure shows a sample <items> XML element for the Disable Event Reporting operation. <items> XML element for the Disable Event Reporting operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell -Dev1</component-name> </item> </items>
The following figure shows a sample adapter request for the Disable Event Reporting operation. Adapter request for the Disable Event Reporting operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <cell-name>Admin</cell-name> <timeout-secs>100</timeout-secs> <user-name>user</user-name> </connection-parameters> <operation-name>disable-event-reporting</operation-name> <component-name>EM Cell-Dev1</component-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Disable Event Reporting operation. Adapter response for the sample Disable Event Reporting operation
570
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> </response-metadata> <proactivenet-performance-manager-maintenance-mode-response> <maintenance-mode-responses> <maintenance-mode-response> <component-name>EM Cell -Dev1</component-name> <component-id>252</component-id> <return-code>0</return-code> <return-message></return-message> </maintenance-mode-response> </maintenance-mode-responses> </proactivenet-performance-manager-maintenance-mode-response> </bmc-proactivenet-performance-manager-response>
Resume Event Reporting operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Resume Event Reporting operation enables you to resume the reporting on a cell specified in the request. Note This operation requires propagation rules to be set in BMC ProactiveNet Performance Manager. For more information, see Propagation rules for maintenance mode for BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager. The following figure shows a sample <items> XML element for the Resume Event Reporting operation. <items> XML element for the Resume Event Reporting operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <component-name>EM Cell Dev1</component-name> </item> </items>
The following figure shows a sample adapter request for the Resume Event Reporting operation. Adapter request for the Resume Event Reporting operation
571
<bmc-proactivenet-performance-manager-request> <connection-parameters> <cell-name >somecell</cell-name> <timeout-secs>100</timeout-secs> <user-name>someuser</user-name> </connection-parameters> <operation-name>resume-event-reporting</operation-name> <component-name>EM Cell -Dev1</component-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Resume Event Reporting operation. Adapter response for the sample Resume Event Reporting operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> </response-metadata> <proactivenet-performance-manager-maintenance-mode-response> <maintenance-mode-responses> <maintenance-mode-response> <component-name>EM Cell -Dev1</component-name> <component-id>252</component-id> <return-code>0</return-code> <return-message></return-message> </maintenance-mode-response> </maintenance-mode-responses> </proactivenet-performance-manager-maintenance-mode-response> </bmc-proactivenet-performance-manager-response>
Adapter requests and responses for the Retrieve operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
This section illustrates the adapter requests and responses for the following Retrieve operations and describes the elements used in the requests. Retrieve Events Retrieve Event by Date Retrieve Events by Component Retrieve Events by ID You can execute additional operations with the following search criteria: Category Component ID Component Type Date (Origin Time) Host Host Address Host Class Location Message
572
Occurrences (Count) Owner Priority Service Severity Status Time to Close (Duration) Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Retrieve Events operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Retrieve Events operation enables you to retrieve events that match all the search criteria specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events operation. <items> XML element for the Retrieve Events operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>My Event ID</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Component Type</name> <value>My Component Type</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Component ID</name> <value>My Component ID</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Category</name> <value>My Category</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Time to Close</name> <value>150</value> <filter-criteria>equals</filter-criteria> </argument>
573
<argument> <name>Host</name> <value>My Host Name</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Host Class</name> <value>Computer</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Host Address</name> <value>10.10.75.167</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Location</name> <value>synapse.com</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Message</name> <value>User1 was here</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Owner</name> <value>user</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Priority</name> <value>2 - High</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Severity</name> <value>CRITICAL</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Service</name> <value></value> </argument> <argument> <name>Status</name> <value>Acknowledged</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Occurences</name> <value>1</value> <filter-criteria>equals</filter-criteria> </argument> <argument> <name>Origin Time</name>
574
<value>12/13/07 3:46 AM</value> <filter-criteria>equals</filter-criteria> </argument>
575
The following figure shows a sample adapter request for the Retrieve Events operation. Adapter request for the Retrieve Events operation
<bmc-proactivenet-performance-manager-request> <operation-name>retrieve-event</operation-name> <connection-parameters> <cell-name >somecell</cell-name> <timeout-secs>100</timeout-secs> <user-name>someuser</user-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>mc.1828.1210339483775</value> </argument> <argument> <name>Severity</name> <value>Info</value> </argument> </arguments> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Retrieve Events operation. Adapter response for the sample Retrieve Events operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> </proactivenet-performance-manager-query-response> <query-executed>select [mc_date_modification, status, severity, mc_owner, mc_smc_id, mc_host, mc_notes, mc_incident_time, msg, mc_priority, duration, mc_smc_type, mc_service, mc_local_reception_time, mc_action_count, mc_arrival_time, mc_host_class, mc_event_category, date_reception, mc_host_address, mc_location, mc_ueid, CLASS, mc-tool, adapter-host, mc-tool-class, mc-tool-address, mc-tool-rule, mc-tool-time, mc_account, mc_object_class, mc_parameter, mc_object, mc_parameter_threshold, mc-smc-alias] from EVENT where [$THIS.mc_ueid equals 'mc.1828.1210339483775'] END</query-executed> <query-response> <Modified>1210346577</Modified> <Status>CLOSED</Status> <Severity>INFO</Severity> <Owner><Owner>
576
<Component_ID>EM_Cell_Server_1 -Dev1</Component_ID> <Host>s-17124</Host> <Notes>0x482915dcuserTEST NOTES MESSAGE0x48290d85userTEST NOTES MESSAGE0x4824b97fuserSETUP VALIDATION TEST NOTE</Notes> <Origin_Time>0</Origin_Time> <Message>TIKOPsIKO1</Message> <Priority>PRIORITY_2</Priority> <Time_to_Close>7104</Time_to_Close> <Component_Type></Component_Type> <Service></Service> <Received>1210339473</Received> <Occurences>0</Occurences> <Arrived>1210339473</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1210339473</Occurred> <Host_address></Host_address> <Location>Unknown</Location> <ID>mc.1828.1210339483775</ID> <CLASS>MC_CELL_PARSE_ERROR</CLASS> <mc-tool>bppm-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>ro-adapter-BMC-ProactiveNet-Performance-manager -actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmcproactivenetperformance manageractoradapter </mc-tool-address> <mc-tool-rule>testMCTOOLRULE</mc-tool-rule> <mc-tool-time>1214236542</mc-tool-time> <mc_account>testAccount</mc_account> <mc_object_class>testObjectClass</mc_object_class> <mc_parameter>testParameter</mc_parameter> <mc_object>testObject</mc_object> <mc_parameter_threshold>testParameterThreshold</mc_parameter_threshold> <mc-smc-alias>EM_Cell_Server_1_India-Dev1</mc-smc-alias>
577
</query-response> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Retrieve Event by Date operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Retrieve Event by Date operation enables you to retrieve events matching the origin time specified in the request. The following figure shows a sample <items> XML element for the Retrieve Event by Date operation. <items> XML element for the Retrieve Event by Date operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Origin Time</name> <value>10/30/07 12:47 PM</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Retrieve Event by Date operation. Adapter request for the Retrieve Event by Date operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Origin Time</name> <value>10/30/07 12:47 PM</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-proactivenet-performance-manager-request>
578
The following figure illustrates the adapter response for the sample Retrieve Event by Date operation. Adapter response for the sample Retrieve Event by Date operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>2</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_incident_time greater_or_equals '1295516760' AND $THIS.mc_incident_time smaller_or_equals '1295516820'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host>2k3std64bitvm2</Host> <adapter_host>2k3std64bitvm2</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.84</mc_tool_address> <Account></Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>OK</Severity> <Modified>1295516770</Modified> <Parameter_Threshold></Parameter_Threshold> <Host_Address>10.128.248.84</Host_Address> <ID>mc.india.d380462.0</ID> <mc_tool_time>1295516770</mc_tool_time> <Parameter></Parameter> <Origin_Time>1295516768</Origin_Time> <mc_tool>Security</mc_tool> <Object>adapter</Object> <mc_tool_class>EventLog</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID></Component_ID> <Message>Successful Network Logon: User Name: Domain: Logon ID: (0x0,0x536CABD) Logon Type: 3 Logon Process: NtLmSsp Authentication Package: NTLM Workstation Name: BMC-TEST
579
Logon GUID: Caller User Name: Caller Domain: Caller Logon ID: Caller Process ID: Transited Services: Source Network Address: 10.128.249.22 Source Port: 0 </Message> <Location>Unknown</Location> <Rule></Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516768</Occurred> <Category></Category> <Class>WIN_EL_SECURITY</Class> <Received>1295516770</Received> <Host_Class></Host_Class> <Arrived>1295516770</Arrived> <Object_Class></Object_Class> <SMC_Alias></SMC_Alias> </query-response>
580
</query-responses> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Retrieve Events by Component operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Retrieve Events by Component operation enables you to retrieve events matching the component type or component ID specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events by Component ID operation. <items> XML element for the Retrieve Event by Component ID operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Component ID</name> <value>EM_Cell_Server_1_India-Dev1</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for the Retrieve Events by Component ID operation. Adapter request for the Retrieve Events by Component ID operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> <connection-parameters> <arguments> <argument> <name>Component ID</name> <value>EM_Cell_Server_1_India-Dev1</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-proactivenet-performance-manager-request>
581
The following figure illustrates the adapter response for the sample Retrieve Event by Component ID operation. Adapter response for the sample Retrieve Event by Component ID operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>3</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_smc_id equals 'EM_Cell_Server_1_India-Dev1'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>MINOR</Severity> <Modified>1295516607</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>India.BEMActor.9103955</ID> <mc_tool_time>1295516571</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>viresh smoke test</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516607</Occurred> <Category>OPERATIONS_MANAGEMENT</Category>
582
<Class>MC_CELL_PARSE_ERROR</Class> <Received>1295516607</Received> <Host_Class></Host_Class> <Arrived>1295516607</Arrived> <Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>MINOR</Severity> <Modified>1295516786</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BPPMActor.5396431</ID> <mc_tool_time>1295516752</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>test message</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295516786</Occurred> <Category>OPERATIONS_MANAGEMENT</Category> <Class>MC_CELL_PARSE_ERROR</Class> <Received>1295516786</Received> <Host_Class></Host_Class> <Arrived>1295516786</Arrived> <Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account>testAccount</Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close>
583
<Severity>MINOR</Severity> <Modified>1295520241</Modified> <Parameter_Threshold>testThreshold</Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BEMActor.6500802</ID> <mc_tool_time>1295520206</mc_tool_time> <Parameter>testParameter</Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object>testObject</Object> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <Message>test message 2</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_5</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295520241</Occurred> <Category>OPERATIONS_MANAGEMENT</Category> <Class>MC_CELL_PARSE_ERROR</Class> <Received>1295520241</Received> <Host_Class></Host_Class> <Arrived>1295520241</Arrived> <Object_Class>testClass</Object_Class> <SMC_Alias>testSMCAlias</SMC_Alias> </query-response>
584
Retrieve Events by ID operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Retrieve Events by ID operation enables you to retrieve events matching the event ID specified in the request. The following figure shows a sample <items> XML element for the Retrieve Events by ID operation. <items> XML element for the Retrieve Events by ID operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>india.BPPM.6500802</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> </item> </items>
The following figure shows a sample adapter request for Retrieve Events by ID operation. Adapter request for Retrieve Events by ID operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>india.BPPM.6500802</value> <filter-criteria>equals</filter-criteria> </argument> </arguments> <operation-name>retrieve-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Retrieve Event by ID operation.
585
Adapter response for the sample Retrieve Event by ID operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-executed>select [mc_service, mc_host, adapter_host, mc_propagations, mc_tool_address, mc_account, mc_action_count, duration, severity, mc_date_modification, mc_parameter_threshold, mc_host_address, mc_ueid, mc_tool_time, mc_parameter, mc_incident_time, mc_tool, mc_object, mc_tool_class, mc_relation_source, mc_owner, mc_smc_id, msg, mc_location, mc_tool_rule, mc_priority, mc_notes, status, mc_smc_type, date_reception, mc_event_category, CLASS, mc_local_reception_time, mc_host_class, mc_arrival_time, mc_object_class, mc_smc_alias] from CORE_EVENT where [$THIS.mc_ueid equals 'india.BEMActor.15243905'] END</query-executed> <query-responses> <query-response> <Service></Service> <Host></Host> <adapter_host>global-rbsjn05o.global-rbsjn05o</adapter_host> <propagations></propagations> <mc_tool_address>10.128.248.121-CDP1-BEMActor</mc_tool_address> <Account></Account> <Occurences>0</Occurences> <Time_to_Close>0</Time_to_Close> <Severity>CRITICAL</Severity> <Modified>1295510258</Modified> <Parameter_Threshold></Parameter_Threshold> <Host_Address></Host_Address> <ID>india.BEMActor.15243905</ID> <mc_tool_time>1295510224</mc_tool_time> <Parameter></Parameter> <Origin_Time>0</Origin_Time> <mc_tool>BEMActor</mc_tool> <Object></Object> <mc_tool_class>ro-adapter-BMC-proactivenetperformance -manager-actor</mc_tool_class> <Relation></Relation> <Owner></Owner> <Component_ID></Component_ID> <Message>Create Items</Message> <Location>Unknown</Location> <Rule>Create Items Workflow</Rule> <Priority>PRIORITY_2</Priority> <Notes></Notes> <Status>OPEN</Status> <Component_Type></Component_Type> <Occurred>1295510258</Occurred> <Category></Category>
586
<Class>EVENT</Class> <Received>1295510258</Received> <Host_Class></Host_Class> <Arrived>1295510258</Arrived> <Object_Class></Object_Class> <SMC_Alias></SMC_Alias> </query-response>
587
Adapter requests and responses for the Update operations for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
This section illustrates the adapter requests and responses for the following Update operations and describes the elements used in the requests: Update Event Acknowledge Event Annotate Event Assign Event Close Event Reopen Event Set Event Priority Set Action Result To keep track of what operations took place on an event on the cells, the Assign Event, Close Event, Reopen Event, and Set Event Priority operations update the Operation History tab of the BMC ProactiveNet Operations Console. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Update Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Update Event operation enables you to update events retrieved using the search criteria specified in the request. The following figure shows a sample <items> XML element for the Update Event operation. <items> XML element for the Update Event operation
588
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>test1</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Update Event operation. Adapter request for the Update Event operation
589
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> <argument> <name>Message</name> <value>Insert message here</value> </argument> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the adapter response for the sample Update Event operation. Adapter response for the sample Update Event operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-executed>select [event_handle, mc_date_modification, status, severity, mc_owner, mc_smc_id, mc_host, mc_incident_time, msg, mc_priority, duration, mc_smc_type, mc_service, mc_local_reception_time, mc_action_count, mc_arrival_time, mc_host_class, mc_event_category, date_reception, mc_host_address, mc_location, mc_ueid, CLASS, mc-tool, adapter-host, mc-tool-class, mc-tool-address, mc-tool-rule, mc-tool-time, mc_account, mc_object_class,mc_parameter, mc_object, mc_parameter_threshold, mc-smc-alias] from EVENT where [$THIS.mc_incident_time greater_or_equals '1193728620' AND $THIS.mc_incident_time smaller_or_equals '1193728680'] END</query-executed> 17863</Time_to_Close> <Component_Type>BMC_AdministrationApplication</Component_Type> <Service></Service>
590
<Received>1196423411</Received> <query-response> <event-handle>124919</event-handle> <Modified>1199286532</Modified> <Status>ACK</Status> <Severity>OK</Severity> <Owner>SOMEONE</Owner> <Component_ID>IAS_Admin@india-dev1</Component_ID> <Host>india-dev1</Host> <Origin_Time>1193728671</Origin_Time> <Message>TEST MESAGE</Message> <Priority>PRIORITY_5</Priority> <Time_to_Close>55 <Occurences>1</Occurences> <Arrived>1196423411</Arrived> <Host_Class></Host_Class> <Category>OPERATIONS_MANAGEMENT</Category> <Occurred>1193728671</Occurred> <Host_Address></Host_Address> <Location>Unknown</Location> <ID>mc.Admin.74ff8f3.0</ID> <CLASS>MC_CELL_PARSE_ERROR</CLASS> <mc-tool>bppm-actor-adapter</mc-tool> <adapter-host>D-13120.synapse.com</adapter-host> <mc-tool-class>ro-adapter-BMC-proactivenetperformance-manager-actor</mc-tool-class> <mc-tool-address>10.10.75.137-null-bmcproactivenetperformance-manageractoradapter </mc-tool-address> <mc-tool-rule>testMCTOOLRULE</mc-tool-rule> <mc-tool-time>1214236542</mc-tool-time> <mc_account>testAccount</mc_account> <mc_object_class>testObjectClass</mc_object_class> <mc_parameter>testParameter</mc_parameter> <mc_object>testObject</mc_object> <mc_parameter_threshold>testParameterThreshold </mc_parameter_threshold> <mc-smc-alias>EM_Cell_Server_1_India-Dev1</mc-smc-alias>
591
</query-response> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Acknowledge Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Acknowledge Event enables you to acknowledge events retrieved using the search criteria specified in the request. The following figure shows a sample <items> XML element for the Acknowledge Event operation. <items> XML element for the Acknowledge Event operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BPPM.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>acknowledged</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Acknowledge Event operation. Adapter request for the Acknowledge Event operation
592
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>acknowledged</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the response for the sample Acknowledge Event operation. Adapter response for the Acknowledge Event operation
593
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>ACK</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCProactiveNetPerformance Manager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353562</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>ro-adapter-BMC-proactivenetperformancemanager-actor</mc_tool_class> <Notes /> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCProactiveNetPerformanceManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BPPM.1232352705131</ID> </query-response> </query-responses> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Annotate Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
594
The Annotate Event operation adds a message to the events retrieved with the search criteria specified in the request. The following figure shows a sample <items> XML element for the Annotate Event operation. <items> XML element for the Annotate Event operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Notes</name> <value>User1 Annotating an event</value> </argument> </update-arguments> <arguments> <argument> <name>ID</name> <value>mc.akatkar-pun-01.97ff50a.0</value> </argument> </arguments> <operation-name>update-event</operation-name> </item> </items>
The following figure shows a sample adapter request for the Annotate Event operation. Adapter request for the Annotate Event operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Notes</name> <value>User1 Annotating an event</value> </argument> </update-arguments> <arguments> <argument> <name>ID</name> <value>mc.akatkar-pun-01.97ff50a.0</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
595
The following figure illustrates the response for the Annotate Event operation. Adapter response for the Annotate Event operation
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query>ntadd 0 's-17127.BMCproactiveNetPerformance -manager-query-responseManager.1232352705131' "TEST NOTES MESSAGE"</query> <query-responses> <notes> <note> <create-date>1232353678000</create-date> <user-name>RBA BPPM Adapter</user-name> <message>TEST NOTES MESSAGE</message> </note> </notes> </query-responses> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Assign Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Assign Event operation enables you to assign events that are retrieved to a specified user. The following figure shows a sample <items> XML element for the Assign Event operation. <items> XML element for the Assign Event operation
596
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>Owner</name> <value>user</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Assign Event operation. Adapter request for the Assign Event operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Owner</name> <value>user</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the response for the sample Assign Event operation. Adapter response for the sample Assign Event operation
597
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>ASSIGNED</Status> <Owner>SOMEONE</Owner> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCProactiveNet PerformanceManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353757</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BPPM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCProactiveNetPerformanceManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BPPM.1232352705131</ID> </query-response> </query-responses> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Close Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
598
The Close Event operation enables you to close events retrieved by the request. The following figure shows a sample <items> XML element for the Close Event operation. <items> XML element for the Close Event operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BPPM.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>Closed</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Close Event operation. Adapter request for the Close Event operation
bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>Closed</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the response for the sample Close Event operation.
599
Adapter response for the sample Close Event operation

<bmc-proactivenet-performance-manager-response> <response-metadata> <proactivenet-performance-manager-query-response> <count>1</count> <query-response> <mc_tool_time>1232352704</mc_tool_time> <Priority>PRIORITY_2</Priority> <Rule>Rule_testing</Rule> <mc_tool_address>10.10.75.131-CDP1-BMCProaactiveNetPerformanceManager </mc_tool_address> <Modified>1232353757</Modified> <mc_tool_class>bmc-adapter-bmc-proactivenet-performancemanager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BPPM Adapter18 TEST NOTES MESSAGE</Notes> <Time_to_Close>0</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing </Parameter_Threshold> <mc_tool>BMCProactiveNetPerformanceManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <ID>s-17127.BPPM.1232352705131</ID> </query-response> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Reopen Event operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
The Reopen Event operation enables you to reopen events that are retrieved using the search criteria. Reopening an event clears the current event owner for the event. The following figure shows a sample <items> XML element for the Reopen Event operation. <items> XML element for the Reopen Event operation
600
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <arguments> <argument> <name>ID</name> <value>s-17127.BPPM.1232352705131</value> </argument> </arguments> <update-arguments> <argument> <name>Status</name> <value>Open</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Reopen Event operation. Adapter request for the Reopen Event operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Status</name> <value>Open</value> </argument> </update-arguments> <arguments> <argument> <name>Severity</name> <value>ok</value> </argument> </arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure illustrates the response for the sample Reopen Event operation. Adapter response for the sample Reopen Event operation
601
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-responses> <query-response> <Severity>MAJOR</Severity> <Status>OPEN</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Testing again</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCProactiveNet PerformanceManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232353915</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance -manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BPPM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>1263</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCProactiveNetPerformanceManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BPPM.1232352705131</ID> </query-response> </query-responses> </proactivenet-performance-manager-query-response> </bmc-proactivenet-performance-manager-response>
Set Event Priority operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
602
The Set Event Priority operation sets the priority of the events that are retrieved using the search criteria. The following figure shows a sample <items> XML element for the Set Event Priority operation. <items> XML element for the Set Event Priority operation
<items> <item> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-arguments> <argument> <name>Priority</name> <value>2 - High</value> </argument> </update-arguments> </item> </items>
The following figure shows a sample adapter request for the Set Event Priority operation. Adapter request for the Set Event Priority operation
<bmc-proactivenet-performance-manager-request> <connection-parameters> <user-name>user</user-name> <timeout-secs>100</timeout-secs> <cell-name>Admin</cell-name> </connection-parameters> <update-agruments> <argument> <name>Priority</name> <value>2 - High</value> </argument> </update-arguments> <operation-name>update-event</operation-name> </bmc-proactivenet-performance-manager-request>
The following figure shows the response for the sample Set Event Priority operation. Adapter response for the sample Set Event Priority operation
603
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>1</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-responses> <query-response> <Severity>OK</Severity> <Status>OPEN</Status> <Owner /> <mc_tool_time>1232352704</mc_tool_time> <Class>EVENT</Class> <Origin_Time>0</Origin_Time> <Message>Message testing</Message> <Priority>PRIORITY_2</Priority> <Service /> <Occurences>0</Occurences> <Received>1232352562</Received> <Rule>Rule_testing</Rule> <Arrived>1232352562</Arrived> <Host_Class>major</Host_Class> <SMC_Alias /> <mc_tool_address>10.10.75.131-CDP1-BMCProactiveNet PerformanceManager</mc_tool_address> <Occurred>1232352562</Occurred> <Host_Address>2 - High</Host_Address> <Account>Account_testing</Account> <Modified>1232354163</Modified> <Host>s-17124</Host> <Component_ID>EM_Cell_Server_1_India-Dev1</Component_ID> <mc_tool_class>bmc-adapter-bmc-proactivenet-performance-manager-actor</mc_tool_class> <Notes>10 0x4974398e15 RBA BPPM Adapter18 TEST NOTES MESSAGE</Notes> <Object>Object_testing</Object> <Component_Type /> <Time_to_Close>1263</Time_to_Close> <Parameter_Threshold>Parameter threshold_testing</Parameter_Threshold> <Object_Class>Object Class_testing</Object_Class> <adapter_host>realops-linux.realopsqa.com</adapter_host> <mc_tool>BMCProactiveNetPerformanceManager</mc_tool> <Category>SLA_MANAGEMENT</Category> <Parameter>Parameter_testing</Parameter> <Location>s-17124</Location> <ID>s-17127.BPPM.1232352705131</ID> </query-response> </query-responses> </proactivenet-performance-query-response> </bmc-proactivenet-performance-manager-response>
Set Action Result operation for BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performance Manager
604
The Set Action Result operation enables you to set the result of a Cell-Action-Result event on BMC ProactiveNet Performance Manager. The monitor adapter captures the remote action event information sent by BMC ProactiveNet Performance Manager. This information is processed by BMC Atrium Orchestrator workflows for executing actions. The action results are forwarded by the actor adapter to BMC ProactiveNet Performance Manager.
Configuring the cell for extended events
You must set up BMC ProactiveNet Performance Manager to generate extended events for the Set Action Result operation.
To set up the cell to generate extended events
1. Add an entry for the monitor adapter in the installHome\pw\server\etc\mcell.dir file, in the following format: cell monitorName mc hostName/portNumber monitorName is the name of the monitor adapter mc is the encryption key portNumber is the port on which the hostName computer listens 2. Add an action rule to the cell Knowledge Base (KB) by creating a test_rba.mrl file in the $ MCELL_HOME \pw\server\etc\ cellName \kb\rules directory. cellName is the name of the Admin or any other processing cell. The test_rba.mrl file must contain the following action rule: action test_rba_1 : EVENT($E) admin_execute(monitorName ,$E, action1 ,[], YES ); END monitorName is the name of the monitor adapter action1 is the action to be performed on the event within BMC Atrium Orchestrator, YES indicates that the action result event is updated with the result of the action when the event terminates in BMC Atrium Orchestrator 3. Compile the cell KB: mccomp -n cell1 The cell name is cell1. 4. Restart the cell: mcell -n cell1 5. Test by sending one or more events to the cell: mposter -n cell1 -a EVENT -m 'test event 1' 6. Trigger the action on the event. A new event of the class, MC_CELL_ACTION_RESULT is generated. The following figure shows a sample <items> XML element for the Set Action Result operation. <items> XML element for the Set Action Result operation
605
<items> <item> <connection-parameters> <timeout-secs>100</timeout-secs> <cell-name>realops-qa13</cell-name> </connection-parameters> <arguments> <argument> <name>ActionResultId</name> <value>1</value> </argument> <argument> <name>ExitCode</name> <value>0</value> </argument> <argument> <name>OutputText</name> <value>testaccount123</value> </argument> <argument> <name>ErrorText</name> <value>testobjectclass123</value> </argument> </arguments> </item> </items>
The following figure shows the sample adapter request for the Set Action Result operation. Adapter request for the Set Action Result operation
606
<bmc-proactivenet-performance-manager-request> <connection-parameters> <timeout-secs>100</timeout-secs> <cell-name>realops-qa13</cell-name> </connection-parameters> <arguments> <argument> <name>ActionResultId</name> <value>1</value> </argument> <argument> <name>ExitCode</name> <value>0</value> </argument> <argument> <name>OutputText</name> <value>testaccount123</value> </argument> <argument> <name>ErrorText</name> <value>testobjectclass123</value> </argument> </arguments> <operation-name>set-action-result</operation-name> </bmc-proactivenet-performance-manager-request>
Note The request for the Set Action Result operation returns a response that does not query the actual updated event. Hence, the count in the XML response is 0, even if the event is successfully updated. Also, no event fields are displayed in the XML response.
Note You must enclose argument values containing special characters or XML code within CDATA as follows: <value><![CDATA[ complexArgumentValue ]]></value> For the Set Action Result operation, the OutputText and ErrorText arguments might contain special characters or XML code. The following figure illustrates the response for the sample Set Action Result operation. Adapter response for the sample Set Action Result operation
607
<bmc-proactivenet-performance-manager-response> <response-metadata> <status>success</status> <count>0</count> </response-metadata> <proactivenet-performance-manager-query-response> <query-responses /> </proactivenet-performance-query-response> </bmc-proactivenet-performance-manager-response>
BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager
he monitor adapter receives events from BMC ProactiveNet Performance Manager and other sources, like the msend command, and Impact Integration Web Server (IIWS) on the BEM gateway. You must specify the gateway name, port, and encryption key in the monitor adapter configuration. These elements are the interface to the BMC ProactiveNet Performance Manager gateway definitions. Therefore, these elements must match the BMC ProactiveNet Performance Manager gateway definitions in the mcell.dir and incomm.conf files to capture the events sent to the monitor adapter. To use the monitor adapter, you must configure cells to forward events to the gateway in the BMC Impact Administration Server environment. For details about the configuration elements for the monitor adapter, see the Node elements for configuring the monitor adapter table. Note BMC Atrium Orchestrator 20.11.01 and later is integrated with BMC Event Manager within the BMC ProactiveNet Performance Manager solution. For information about configuring the BMC ProactiveNet Performance Manager cell to send events to the monitor adapter, see the BMC ProactiveNet Administrator Guide. The monitor adapter handles the events in the following sequence: 1. The monitor adapter listens on the BMC ProactiveNet Performance Manager gateway that is set up on the BMC ProactiveNet Performance Manager server to detect and handle events. 2. The rules in the module configuration are then triggered by the event to handle the designed workflow.
Setting up events for the BMC Atrium Orchestrator Monitor Adapter for the BMC ProactiveNet Performance Manager
The monitor adapter does not use the mcell.dir file that is local to the BMC Atrium Orchestrator peer. To enable propagation of events from the cells to the gateway, you must make changes to the mcell.dir file on BMC ProactiveNet Performance Manager. However, if you need to change the listener port in the monitor adapter configuration, you must also make this change in the mcell.dir file on the BMC ProactiveNet Performance Manager server.
To enable propagation of events from BMC ProactiveNet Performance Manager cells to the gateway
1. Create the gateway.imcomm file on the BMC ProactiveNet Performanc Manager server in the installHome\pw\server\etc directory. 2. Add the following line to define the gateway in the mcell.dir file:
608
BMC Atrium Orchestrator Application Adapters 20.11.02 2.
Example gateway.imcomm gw mc 10.10.75.88:1859 The variables are defines as follows: gw: gateway name mc: encryption key 10.10.75.88: IP address of the peer local to BMC Atrium Orchestrator 1859: port on which the monitor adapter listens for events
3. Restart the mcell services. The following figure illustrates a sample gateway.imcomm file. Sample gateway.imcomm file
#cond.new=propagate #cond.mod=always #drop.mod=[] #drop.new=[] #add.mod=[] #add.new=[] slots.new=[$ALL] slots.mod=[mc_ueid, $MODS] #modify.mod=[] #--------------------------------------------------------------# Format parameters - MAY NOT BE MODIFIED or message will be not acknowledged by ImGateway #--------------------------------------------------------------init.new=$CLASS;\n init.mod=modify $GHANDLE;\n body=\t$NAME=$VALUE;\n term=END\n #separator= #quoatable=<standard MRL quotation rules> #openquote=' #closequote=' #escapequote='
Propagating events from the cells to the gateway for the BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager
You must set up a propagation rule to ensure that events are propagated from the cells to the gateway.
To set up the propagation rule

1. Copy the gatewayim.mrl file to installHome\pw\server\etc\ cellName \kb\rules. 2. Set the name of the relevant gateway ( gw1 ) in the gatewayim.mrl file as shown in the following sample:
propagate p:EVENT to gw1 END
3. Add an entry for gatewayim in the .load file at installHome\pw\server\etc\ cellName \kb\rules to load the
609
BMC Atrium Orchestrator Application Adapters 20.11.02 3. gatewayim.mrl file. 4. Navigate to the installHome\pw\server\etc\ cellName \kb directory and compile the knowledge base by executing the following command: mccomp manifest.kb 5. Restart the cell. For more information about propagation rules, see Propagation rules for the maintenance mode for BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager.
Module configuration for BMC ProactiveNet Performance Manager

Module configuration maps external slot names (as used in the XML requests and responses) to slot names that are referenced by the wrapper validations. You can customize external slot names by specifying a custom mapping file in the adapter configuration and use those slot names for validations. Note If you specify a custom mapping file, ensure that you change the corresponding external name in the module configuration for the validations to work as desired.The module configuration lists only the slot names that are used in the validations. Module configuration contains a BMC_ProactiveNet_Performance_Manager group that defines static string mappings of certain slot names mapped to their external values. You can modify the external slot names by specifying the slot names in the custom slot name mapping file referenced using the <request-field-mapping-file-location> element of the adapter configuration. For details about the configuration elements for the actor adapter, see Node elements for configuring the actor adapter. Note Change the module configuration only if the changed slot names are present in the module configuration.
Propagation rules for the maintenance mode for BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager
Propagation rules ensure that event reporting does not occur on components in the maintenance mode. By default, a propagation rule is defined in the gatewayim.mrl file for each component that is installed on BMC ProactiveNet Performance Manager. The gatewayim.mrl file is part of BMC ProactiveNet Performance Manager. For example, suppose a workflow queries the change management system and detects that an active change is being worked on. To avoid reporting events on the component when it is in maintenance mode, you configure a propagation rule in the gatewayim.mrl file. Note By default, a propagation rule allows event reporting on configured components. To use an adapter request for the disable-event-reporting operation or resume-event-reporting operation in a process, a propagation rule must be set up. The information for the propagation rule is set in the gatewayim.mrl file.
610
Sample propagation rule for maintenance mode

$CI.mc_udid == $EV.mc_smc_id AND $EV.mc_smc_id \!= ''
BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performance Manager event
The monitor adapter receives traps published by BMC ProactiveNet Performance Manager. To perform actions related to traps, you design processes and implement rules. The following figure illustrates a sample monitor adapter event. Sample monitor adapter event
<event> <date-reception><![CDATA[1200910937]]></date-reception> <mc-arrival-time><![CDATA[1200910937]]></mc-arrival-time> <mc-local-reception-time><![CDATA[1200910937]]></mc-local-reception-time> <severity><![CDATA[CRITICAL]]></severity> <msg><![CDATA[HI THERE]]></msg> <mc-priority><![CDATA[PRIORITY_1]]></mc-priority> <mc-ueid><![CDATA[mc.Dev1.7947259.0]]></mc-ueid> <date><![CDATA[20080121155217.000000+330]]></date> <mc-date-modification><![CDATA[1200910937]]></mc-date-modification> <mc-location><![CDATA[Unknown]]></mc-location> <mc-history><![CDATA[['Dev1:97522']]]></mc-history> </event>
Troubleshooting specific to BMC Atrium Orchestrator Application Adapter for BMC ProactiveNet Performanance Manager
This section lists troubleshooting specific to BMC ProactiveNet Performanance Manager.
Event with WARNING severity received by the BMC Atrium Orchestrator Monitor Adapter for BMC ProactiveNet Performanance Manager but slot severity in event is not received
WARNING is the default severity value in the BMC ProactiveNet Performanance Manager application. To resolve this issue, you must add a configuration parameter to the gateway.imcomm file.
To add the configuration parameter
1. Access the computer on which BMC ProactiveNet Performanance Manager is installed and navigate to the installHome\pw\server\etc directory. 2. Open the gateway.imcomm file and the add the following line:
cond=always
3. Restart the BMC ProactiveNet Performanance Manager service.
611
Unable to monitor events from the admin or any other cell

1. If the mcell.conf file in $ MCELL_HOME \pw\server\etc\ cellName has serverDirectoryName=C:\Program Files\ProactiveNet\pw\pronto\data\admin\admin.dir, remove the line. 2. Recompile the cell. 3. Restart the cell.
BMC Atrium Orchestrator application adapter for BMC Remedy AR System

The BMC Atrium Orchestrator application adapter for BMC Remedy Action Request System is an application adapter that interacts with the BMC Remedy Action Request System application. The application adapter for BMC Remedy Action Request System contains an actor and a monitor adapter. The following topics provides information about using the BMC Atrium Orchestrator application adapter for BMC Remedy AR System: Using the Integration Mapping Wizard Supported versions for the BMC Remedy AR System adapter Configuring the BMC Atrium Orchestrator Application Adapter for BMC Remedy System BMC Remedy AR System application adapter module Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for Remedy AR System BMC Remedy AR System monitor adapter
Using the Integration Mapping Wizard

Integration Mapping Wizard (IMW) maps the data model employed by the external systems to the normalized internal models. Adapters efficiently and generically describe their respective domain models at run time with the help of IMW. IMW uses client logic and user interfaces to communicate with adapters and render domain objects for mapping. For more details, see the BMC Atrium Orchestrator Development Studio User Guide.
Supported versions for the BMC Remedy AR System adapter

The adapter is compatible with the following versions of BMC Remedy AR System: version 7.0 version 7.5 version 7.6.00 version 7.6.03 version 7.6.04
Configuring the BMC Atrium Orchestrator Application Adapter for BMC Remedy System
You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the BMC Performance Manager Portal application. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user guide into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields on the form view or to configure all the elements and attributes using XML only. However, after you switch to
612
the XML view and save the configuration in the XML from that view, you cannot thereafter use the form view for modifying that configuration.

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. Access the adapters page by clicking the Manage tab; then click the Adapters tab. 3. In the Adapters in Repository list, select the ro-adapter-remedy-actor check box to configure an actor adapter or the ro-adapter-remedy-monitor check box to configure an monitor adapter. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to step 7 to configure the adapter using the XML view: a. Enter a name for the adapter. Note The default name for the Remedy actor adapter is ARSAdapter. b. Enter a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements indicated with an asterisk (*). 7. ( optional ) Configure the adapter in the XML view using the following substeps: a. Enter a name and a description for the adapter. b. Click Switch to XML View. c. On the Warning message that appears, click Switch View. d. Copy the configuration elements and attributes as given in the guide, into the Properties text box, and then click OK. Note If the default value for an optional element is acceptable, omit the element. Do not include empty elements. e. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. If your Remedy AR Server group contains a load balancer, you must configure the load balancer with the Remedy monitor adapter. You use a hardware load balancer to improve the scalability and availability of AR System servers. The load balancer distributes the traffic from multiple clients to several servers, preventing AR System servers from becoming overloaded. A load balancer thus provides solutions to issues relating to performance, hardware capacity, system downtime, and so on in high-load environments. To configure the load balancer, add a mapping for the IP addresses of the load balancer and other servers in the Remedy Server group in the ar.cfg file of each server in the group. For example, let us consider two servers: AR Server 1 and AR Server 2 in the Remedy Server group. The IP address of AR Server 1 is IP1, AR Server 2 is IP2, and load balancer is L-IP. The IP addresses of the load balancer and the other server are mapped as follows to the local AR Server's IP address: For AR Server 1, add the following entries to the corresponding ar.cfg file: Map-IP-Address: L-IP IP1 Map-IP-Address: IP2 IP1 For AR Server 2, add the following entries to the corresponding ar.cfg file:
613
Map-IP-Address: L-IP IP2 Map-IP-Address: IP1 IP2 Note If the Remedy AR Server group uses a load balancer, you must set the following parameters in the ar.cfg file of each server in the Remedy Server group: Alert-Ignore-Actual-Client-IP: T Alert-Send-Timeout: 30
To configure the load balancer with the monitor adapter, see the <target> element description in Configuration node elements for the adapter. The following table describes the elements of an actor adapter configuration that you can specify using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the UI label column. To configure such elements and attributes, you have to switch to XML view. Configuration node elements for the adapter UI label Element None <configs>
Description Contains the configuration and peer mapping nodes for an adapter configuration This element is required, if the <peer-config-mappings> element is used to define peer mapping for configurations. Contains the configuration elements to connect to a specific server, along with login credentials This element can contain an optional <name> attribute to be used as a reference when multiple configurations are defined. The name attribute is required when using the peer mapping feature. Specifies the host name or IP address of the BMC Remedy AR System server Contains the <schema> elements Specifies the BMC Remedy AR System schema to be cached upon adapter attachment to peer, restart of peer, or immediately following a reset-cache action In the absence of this element, the schema is cached the first time after it is called by an adapter request. Specifies the remote connection port number In the absence of this element, a default
None
<config>
Target Schemas Schema
<target> <schemas> <schema>
Port
<port>
614
User Name
<user-name>
Password
<password>
Rpc Number <rpc-number>
value of 0 will be assigned. This default will cause the BMC Remedy AR System to use its default TCP/IP port number. Specifies the user name to be used to connect to the BMC Remedy AR System server Specifies the password that corresponds to the <user-name> specified Specifies the RPC port number In the absence of this element, a default value of 0 will be assigned. The default will cause the BMC Remedy AR System to use its default RPC port number. Contains the mapping nodes for each peer This element is required to define peer mapping for configurations. Contains the peer and configuration mapping elements This feature facilitates peer-specific configuration files, allowing users to assign specific user name and password credentials to each peer. Specifies the name of the peer, as defined in Grid Manager, for which a specific configuration will be assigned This is required to define peer mapping for configurations. Specifies the value of the name attribute for the desired configuration to be used by the peer This is required to define peer mapping for configurations. Schedules the resetting of cache for repeated execution if true Valid values: true (default), false Specifies the successive resetting of cache that takes place at approximately regular intervals, separated by the specified delay The delay is specified in minutes. The default value is 120. Enables the connection pooling provided by the Java API of the BMC Remedy AR System 7.5 Valid values: true, false (default) Configures the proxy pool sizes per server when the value for <use-connection-pooling> is true
None
<peer-config-maps>
None
<peer-config-map>
None
<peer-name>
None
<config-name>
Auto Reset Cache
<auto-reset-cache>
Delay
<delay>
<use-connection-pooling> Use Connection Pooling
<max-connections> Max Connections
615
<max-request-queue-size> Max Request Queue Size
The default value is 100. Specifies the maximum size of the queue maintained by the actor adapter to handle concurrent requests if the value of <use-connection-pooling> is false or not specified The default value is 2147483647. Specifies the directory in which the actor adapter stores the attachments retrieved from the BMC Remedy AR System server The default value is the Java Virtual Machine (JVM) value for java.io.tmpdir . For Microsoft Windows, the default value is C:\DOCUME~1\user\LOCALS~1\Temp\. For Oracle Solaris, the default value is var/tmp/. For Linux , the default value is /tmp. Specifies whether the attachments needs to be downloaded with details or only with details in response Valid values: true, false With a value of true the attachments are downloaded on the configured destination location (configurable through adapter configuration) on disk and the attachment details are returned in the response. With a value of false, the attachment details are returned in the response without downloading the attachment to the specified directory. Specifies whether the attachment to be sent in adapter response is a Base 64 encoded string Valid values: true, false (default) With a value of true, the download attachments process input is not considered. This states that the attachment sent in the adapter response is a Base64 encoded string. If this element is set to false and the download attachments element is set to false, the attachment details are shown only in the response. Reflects the connectivity state of the BMC Remedy AR System server Valid values: true, false (default)
Attachment <attachment-destination-dir> Destination Dir
<download-attachments> Download Attachments
<retrieve- attachment-in-response> Retrieve Attachment In Response
Monitor Server Up Down
<monitor-server-up-down>
616
If the value is set to true, the actor adapter monitors the connection to the BMC Remedy AR System server. If the BMC Remedy AR System server is down, it sets the adapter state to Fault. When the BMC Remedy AR System server comes back online, the adapter returns to the running state. This feature enables the same actor adapters to connect to more than one BMC Remedy AR System server (using peer configuration maps). When the BMC Remedy AR System server is down, all requests are routed to the adapter that is not in the fault state. If the value is set to false, the adapter would not monitor the connectivity state of the BMC Remedy AR System server. Specifies the frequency at which the adapter should monitor the connectivity state of the BMC Remedy AR System server The default value is 30 seconds Specified to increase the normal timeout value in order to execute the adapter request successfully The default value is 120 seconds. The timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed. Note: If the value specified for this parameter is less than or equal to default value, the specified value is ignored and the default value is considered. Specified to increase the long timeout value in order to execute the adapter request successfully The default value is 300 seconds. The timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed. Note: If the value specified for this parameter is less than or equal to default value, the specified value is ignored and default value is considered. Specified to increase the extra long timeout value in order to execute the adapter request successfully The default value is 1800 seconds. The
Monitor Server Frequency Secs
<monitor-server-frequency-secs>
Server Timeout Normal
<server-timeout-normal>
Server Timeout Long
<server-timeout-long>
Server Timeout Extra Long
<server-timeout-extra-long>
617
timeout value for this parameter should be increased if network latency or Remedy AR Server's slow performance is noticed. Note: If you specify a value for this parameter that is less than or equal to default value, the specified value is ignored and default value is considered. Provides the user the ability to set the locale of the Remedy adapter
Client Locale
<client-locale>
The default value is the computer's default locale. <query-response-contains-id-or-name> Specifies whether the value of the name Query attribute in the adapter response to a Response query is a field ID or a field name Contains Id Or Name Valid values: ID (or id), name Note: If you do not specify a value while configuring the adapter, the response contains the value that you specify for the <field> element in the adapter request. The following figure shows an XML template of the adapter configuration for the BMC Remedy AR System actor adapter. XML template for configuring the actor adapter
618
<configs> <config name=' '> <target></target> <schemas> <schema></schema> <schema></schema> </schemas> <port></port> <user-name></user-name> <password></password> <client-locale></client-locale> <server-timeout-normal></server-timeout-normal> <server-timeout-long></server-timeout-long> <server-timeout-extra-long></server-timeout-extra-long> <rpc-number></rpc-number> <auto-reset-cache></auto-reset-cache> <delay></delay> <use-connection-pooling>true</use-connection-pooling> <max-connections>50</max-connections> <attachment-destination-dir></attachment-destination-dir> <download-attachments></download-attachments> <retrieve-attachment-in-response></retrieve-attachment-in-response> <max-request-queue-size></max-request-queue-size> <monitor-server-up-down>false</monitor-server-up-down> <monitor-server-frequency-secs></monitor-server-frequency-secs> <query-response-contains-id-or-name> </query-response-contains-id-or-name> </config> <peer-config-maps> <peer-config-map> <peer-name></peer-name> <config-name></config-name> </peer-config-map> </peer-config-maps> </configs>
The following figure shows an XML sample of the adapter configuration. XML sample of the adapter configuration
<config> <target>vm-w23-rds24</target> <user-name>Demo</user-name> <password>Demo</password> <client-locale>Shift-JIS</client-locale> <server-timeout-normal>180</server-timeout-normal> <server-timeout-long>500</server-timeout-long> <server-timeout-extra-long>2500</server-timeout-extra-long> </config>
619
The following figure shows an XML sample of the adapter configuration that resets the cache automatically after 120 minutes. XML sample of adapter configuration with <auto-reset-cache> element
<config> <target>vm-w23-rds24</target> <user-name>appadmin</user-name> <password>Admin</password> <auto-reset-cache>true</auto-reset-cache> <delay>120</delay> </config>
The following figure shows an XML sample of the adapter configuration using the <attachment-destination-dir> element. XML sample of the configuration with the <attachment-destination-dir> element
<config> <target>vm-w23-rds24</target> <user-name>Demo</user-name> <password /> <auto-reset-cache>true</auto-reset-cache> <delay>120</delay> <attachment-destination-dir>C:\ARS Testing\Download</attachment-destination-dir> <download-attachments>false</download-attachments> <retrieve-attachment-in-response>true</retrieve-attachment-in</config>
response>
The following figure shows an XML sample of the adapter configuration using the <monitor-server-up-down> and <monitor-server-frequency-secs> elements. XML sample of the adapter configuration with the <monitor-server-up-down> and <monitor-server-frequency-secs> elements
<config> <target>arserver-1</target> <user-name>aruser</user-name> <password>arpasswd</password> <monitor-server-up-down>true</monitor-server-up-down> <monitor-server-frequency-secs>10</monitor-server-frequency-secs> .... .... </config>
The following figure shows an XML sample of the adapter configuration when the <query-response-contains-id-or-name> element is set to ID.
620
XML sample of the adapter configuration when <query-response-contains-id-or-name> is set to ID

<config> <target>vm-w23-rds24</target> <user-name>appadmin</user-name> <password>Admin</password> <query-response-contains-id-or-name>ID</query-response-contains-id-or-name> </config>
The following figure shows an XML sample of the adapter configuration using the peer configuration mapping. XML sample of the adapter configuration using the peer configuration mapping
<configs> <peer-config-maps> <peer-config-map> <peer-name>CDP</peer-name> <config-name>C1</config-name> </peer-config-map> <peer-config-map> <peer-name>AP</peer-name> <config-name>C2</config-name> </peer-config-map> </peer-config-maps> <config name="C1"> <target>ARServer1</target> <user-name>U1</user-name> <password>P1</password> <monitor-server-up-down>true</monitor-server-up-down> <monitor-server-frequency-secs>10</monitor-server-frequency-secs> </config> <config name="C2"> <target>ARServer2</target> <user-name>U2</user-name> <password>P2</password> <monitor-server-up-down>true</monitor-server-up-down> <monitor-server-frequency-secs>10</monitor-server-frequency-secs> </config> </configs>
The following table shows the configuration node elements for BMC AR Remedy monitor adapter that you can specify using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the UI label column. To configure such elements and attributes, you have to switch to XML view.
Configuration node elements for monitor adapter
621
UI label None
Element <config>
Description Contains the configuration elements to connect to a specific server, along with login credentials Specifies the host name or IP address of the BMC Remedy AR system server Note: If the Remedy AR Server group uses a load balancer, you must set the <target> element of the monitor adapter to the IP address of the load balancer
Required Yes
Target
<target>
Yes
Schemas Schema
< schemas> < schema>
Contains the <schema> elements Specifies the BMC Remedy AR System schema to be cached upon adapter attachment to a peer, restart of a peer, or immediately following a reset-cache action In the absence of this element, the schema will be cached the first time it is called by an adapter request.
No No
Port
< port>
Specifies the remote connection port number No
In the absence of this element, a default value of '0' will be assigned. This default will cause the BMC Remedy AR System to use its default TCP/IP port number. User Name Password Rpc Number <user-name> <password> <rpc-number> Specifies the user name to connect to the BMC Remedy AR System server Specifies the password that corresponds to the specified <user-name> Specifies the RPC port number In the absence of this element, a default value of '0' will be assigned. The default will cause the BMC Remedy AR System to use its default RPC port number. Poll Interval <poll-interval> Specifies the frequency, in seconds, to re-register with the BMC Remedy AR System host This will re-establish any dropped connections with the BMC Remedy AR System host. In the absence of a specified poll-interval, a default value of '900' will be assigned. This default will prompt for re-registration with the BMC Remedy AR System host every 15 minutes. No Yes No No
622
Alert Listener Port
<alert-listener-port>
Specifies the port on which the adapter will listen for BMC Remedy AR System notifications In the absence of this element, a default value of 0 will be assigned. The default will cause the protocol to provide the first available port on which to listen.
Delete Alerts
<delete-alerts>
Deletes alerts from schema after being marked as read Valid values: true, false Note: If this element is set to true and the <username> provided is for a user with insufficient privileges to delete a record, the alert will remain in the schema, marked as read, and a warning level message will be logged. In the absence of this element, a default value of false will be assigned.
No
<maximum-registration-retries> Specifies the number of retries the adapter Maximum makes to connect to the Remedy AR System Registration application Retries The registration retry frequency is determined by the <polling-interval> element. If the registration fails due to authentication errors, there are no retries. Default value: 3 Maximum Alerts Per Second <maximum-alerts-per-second> Specifies the count of unread alerts to be processed per second It limits the rate at which the monitor adapter retrieves unread alerts from the BMC Remedy AR System server. If the monitor adapter does down for a long period and this parameter is enabled, no Out-of-Memory errors occur. Query <query> Used to provide additional querying capability to add more filtering criteria to the default query
No
No
No
The following figure shows the XML template for monitor adapter configuration. XML template for monitor adapter configuration
623
<config> <target></target> <schemas> <schema></schema> <schema></schema> </schemas> <port></port> <user-name></user-name> <password></password> <rpc-number></rpc-number> <poll-interval></poll-interval> <alert-listener-port></alert-listener-port> <delete-alerts></delete-alerts> </config>
BMC Remedy AR System application adapter module

The processes contained in the adapter module for the BMC Atrium Orchestrator adapter for BMC Remedy AR System are used to execute basic operations to interface with BMC Remedy AR System. These processes determine the version of BMC Remedy AR System being used and call a process from the corresponding process directory. Process directories of version 7.0 and version 7.5 are included in this module and contain processes specifically designed to interface with version 7.0 and later of BMC Remedy AR System.
Top-level processes for the BMC Remedy AR System adapter

The processes contained in the adapter module (AMP-AD-BMC-Remedy-ARS) directory are used to execute basic operations to interface with BMC Remedy AR System. These top-level processes in the Project Explorer execute the following version-specific BMC Remedy AR System processes: [Create Items] [Delete Items] [Find Items] [Query Update Items] [Update Items] [Query Server Info]
The following table maps the adapter processes with the required actions using the Call Adapter Activity.
Call adapter processes mapping to action Adapter process Delete Entry Get Entries Insert Entry Corresponding action delete query set
Query Update Entry query-update Reset Cache Update Entry reset-cache update
624
Query Server Info
query-server-info
Note The Delete Entry, Get Entries, Insert Entry, Query Update Entry, and the Update entry processes can add, update, retrieve, and delete an attachment. The file to be attached to the form must be located on the same computer where the BMC Remedy AR System actor adapter is enabled. Attachments retrieved using an instance of the adapter are stored on the local computer where the adapter is enabled. If the attachments have same file name, the file name of the new attachment is suffixed with the index to avoid overriding the existing file at a given directory location. For example, if the file name of an attachment is attach.txt that already exists in the directory and another attached file name that has to be retrieved has the same name, then the file name is suffixed with an index indicator (attach-1.txt ), and so on.
Create Items
The Create Items process creates one or more records in a specified schema within the BMC Remedy AR System. The following table describes the process input elements for the <items> XML element for the Create Items process. Process inputs - Create Items Process input Description <adapter name> Specifies the name of the adapter to be used for the process, as configured in Grid Manager Required No
<items>
Default value: ARSadapter Specifies the XML document containing the elements required to insert a record into Yes a BMC Remedy AR System schema Note: Values must be provided for each field required by the BMC Remedy AR System to create a complete record. Specifies the version of the BMC Remedy AR System being used Valid values: v7.0, v7.5, v7.6 Indicates the type of record to be created
<version>
Yes
<item type>
No
Note: This input is not currently being used by this process. <batch process Indicates that all <item> elements in the XML document must be processed by the No items> adapter in a batch mode Default value: false The following figure shows a sample <items> XML element for the Create Items process. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. XML sample for input parameter - Create Items
625
<items> <item> <schema>Sample:Cities</schema> <fields> <values> <field name="City">Delhi</field> <field name="Airport Code">Del</field> <field name="Diary Field">Enter data in Diary Field</field> </values> </fields> </item> </items>
The following table describes the process output elements for the Create Items process.
Process output - Create Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates the XML sample of the output parameter for the Create Items process when the <batch-process-items> element is set to false. XML sample for output parameter - adapter response - Create Items when <batch process items> is false
<set-action-result> <entry-id>000000000000179</entry-id> </set-action-result>
The following figure illustrates the XML sample of the output parameters for the Create Items process when the <batch process items> element is set to true. XML sample for output parameter - adapter response - Create Items when <batch process items> is true
626
<set-action-result> <entries> <metadata> <entry-count>2</entry-count> </metadata> <entry> <entry-id>000000000000076</entry-id> </entry> <entry> <entry-id>000000000000077</entry-id> </entry> </entries> </set-action-result>
Delete Items
The Delete Items process removes a record in a specified schema in the BMC Remedy AR System. The following table describes the process input parameters for the <items> XML element for the Delete Items process. Process inputs - Delete Items Process input <adapter name> Description Required Specifies the name of the adapter to be used for the process, as configured in Grid No Manager Default Value: ARSadapter Specifies the XML document containing the elements required to delete a record from a BMC Remedy AR System schema Specifies the version of the BMC Remedy AR System being used Valid values: v7.0, v7.5, and v7.6 Indicates the type of record to be deleted Note: This input is not currently being used by this process. Specifies the XML document containing any additional information required to make the adapter request Note: This input is not currently being used by this process. Indicates that all <item> elements in the XML document must be deleted in a batch mode Default value: false The following figure shows the sample <items> XML element for the Delete Items process. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. XML sample for input parameter - Delete Items
<items> <version>
Yes Yes
<item type>
No
<connection> parameters
No
<batch process items>
No
627
<items> <item> <schema>AR System schema from which entry will be removed</schema> <entry-id>AR System entry ID for the record to be removed</entry-id> </item> </items>
The following figure shows the XML output for the sample Delete Items process when <batch process items> is set to false. XML output - Delete Items when < batch process items > is false
<delete-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> </entries> </delete-action-result>
The following figure illustrates the XML sample of the output parameters for the Delete Items process when <batch process items> is set to true. XML output - Delete Items when < batch process items > is true
<delete-action-result> <entries> <entry> <entry-id>000000000000085</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>000000000000086</entry-id> <entry-count>1</entry-count> </entry> </entries> </delete-action-result>
Find Items
The Find Item process searches a BMC Remedy AR System schema for records matching specified criteria. The following table describes the process input elements for the for the <items> XML element for the Find Items process.
Process inputs - Find Items
628
Process input <adapter name>
Description Specifies the name of the adapter to be used for the process, as configured in Grid Manager Default Value: ARSadapter
Required No
<items> <version>
Specifies the XML document containing the elements required to query a BMC Remedy AR System schema, including the search criteria Specifies the version of the BMC Remedy AR System being used Valid values: v7.0, v7.5, and v7.6
Yes Yes
<item type> Indicates the type of record to be obtained This input is used to define the type of values retrieved and is used as a label for the collection returned. The value is user defined and there is no validation within the process for a specific item type. Common values used are trouble-ticket and outage, depending on whether BMC Remedy AR System is being used for change management or problem management. <connection Specifies the XML document containing additional information required to make the parameters> adapter request Note: This input is not currently being used by this process. The following figure shows the XML sample of the input parameters for the Find Items process. XML sample for input parameter - Find Items
<items> <item> <schema>Sample:Cities</schema> <key>1</key> <value>000000000000019</value> <fields> <field>Request ID</field> <field>Diary Field</field> <field>City</field> <field>Airport Code</field> <field>Modified Date</field> <field>Attachment1</field> <field>Attachment2</field> </fields> </item> </items>
Yes
No
The following table describes the output parameters for the Find Items process. Process output - Find Items Process Description output adapter Specifies the XML document returned by the adapter request executed on the BMC Remedy AR response System
629
Note: The fields returned reflect the fields provided within the <fields> element of the items input parameter.
Note The <fields> node and at least one <field> element must be included.
The following figure illustrates the XML sample of the output parameter for the Find Items process. XML sample for output parameter - adapter response - Find Items
<query-action-result> <entries> <metadata> <entry-count>2</entry-count> </metadata> <entry> <entry-id>000000000000179</entry-id> <field name="first field name">field value</field> <field name="second field name">field value</field> . . . </entry> <entry> <entry-id>000000000000190</entry-id> <field name="first field name">field value</field> <field name="second field name">field value</field> . . . </entry> </entries> </query-action-result>
Query Update Items

The Query Update Items process updates a record in a BMC Remedy AR System schema with one or more values. The following table describes the process input elements for the <items> XML element for the Query Update Items process. Process inputs - Query Update Items Process input <adapter name> Description Required Specifies the name of the adapter to be used for the process, as configured in Grid No Manager Default Value: ARSadapter Specifies the XML document containing the elements required to update a record
<items>
Yes
630
<version>
in a BMC Remedy AR System schema Specifies the version of the BMC Remedy AR System being used Valid values: v7.0, v7.5, and v7.6 Indicates the type of record to be obtained Note: This input is not currently being used by this process. Specifies the XML document containing any additional information required to make the adapter request Note: This input is not currently being used by this process. Indicates that all <item> elements in the XML document must be used to update records in a batch mode Default value: false
Yes
<item type>
No
<connection parameters>
No
No
The following figure shows the XML sample of the input parameter for the Query Update Items process. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. XML sample for input parameter - items - Query Update Items
<items> <item> <field-id>536870914</field-id> <schema>Sample:Cities</schema> <id>Hyd</id> <fields> <field name="Diary Field">Update Diary Field</field> <field name="Attachment1">C:\Test A.txt</field> </fields> </item> </items>
The following table describes the process output parameters for the Query Update Items process.
Process output - Query Update Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates the XML sample of the output parameters for the Query Update process when <batch process items> is set to false. XML sample for output parameter - adapter response - Query Update Items when < batch process items > is false
631
<query-update-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> </entries> </query-update-action-result>
The following figure illustrates the XML sample of the output parameters for the Query Update process when <batch process items> is set to true. XML sample for output parameter - adapter response - Query Update Items when < batch process items > is true
<query-update-action-result> <entries> <entries> <entry> <query>'1'="000000000000130"</query> <entry-count>1</entry-count> </entry> <entry> <query>'1'="000000000000090"</query> <entry-count>1</entry-count> </entry> <entry> <query>'1'="000000000000091"</query> <entry-count>1</entry-count> </entry> </entries> </query-update-action-result>
Update Items
The Update Items process updates entries in a BMC Remedy AR System schema with a specified value. The following table describes the process input for the <items> XML element for the Update Items process. Process inputs - Update Items Process input <adapter name> Description Required Specifies the name of the adapter to be used for the process, as configured in Grid No Manager Default Value: ARSadapter Specifies the XML document containing the elements required to update a record in a BMC Remedy AR System schema Specifies the version of the BMC Remedy AR System being used Valid values: v7.0, v7.5, and v7.6 Indicates the type of record to be obtained
<items> <version>
Yes Yes
<item type>
No
632
<connection> parameters
Note: This input is not currently being used by this process. Specifies the XML document containing any additional information required to make the adapter request
No
Note: This input is not currently being used by this process. Indicates that all <item> elements in the XML document must be used to update a No record in a batch mode Default value: false
The following figure shows the XML sample of the input parameters for the Update Items process. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. XML sample for input parameter - items - Update Items
<items> <item> <schema>Sample:Cities</schema> <updated-field>Diary Field</updated-field> <updated-field-value>Update Diary Field</updated-field-value> <entry-id>000000000000013</entry-id> </item> </items>
The following table describes the process output parameters for the Update Items process.
Process output - Update Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates the XML sample of the output parameters for the Update Items process <batch process items> is set to false. XML sample for output parameter - adapter response - Update Items when < batch process items > is false
<update-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> </entries> </update-action-result>
The following figure illustrates the XML sample of the output parameters for the Update Items process <batch process items> is set to true.
633
XML sample for output parameter - adapter response - Update Items when < batch process items > is true
<update-action-result> <entries> <entry> <entry-id>000000000000004</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>000000000000090</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>000000000000091</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>000000000000092</entry-id> <entry-count>1</entry-count> </entry> </entries> </update-action-result>
Query Server Info

The Query Server Info process gives information about the BMC Remedy AR System server. The following table describes the process input parameters for the Query Server Info process.
Process inputs - Query Server Info Process input adapter name Description Specifies the name of the adapter to be used for the process, as configured in Grid Manager Default Value: ARSadapter The following figure shows an XML sample of the adapter request for the Query Server info process. XML sample of the adapter request for Query Server Info process
<adapter-request> <request-action>query-server-info</request-action> </adapter-request>
Required No
The following table describes the process output parameters for the Query Server Info process.
Process output - Query Server Info
634
Process output adapter response
Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates the XML sample of the output parameters for the Query Server Info process. *XML sample for output parameter - adapter response - Query Server Info*
<server-information> <server-name>vm-w23-rds24</server-name> <server-version>7.1.00 Patch 005 200809150630</server-version> <server-locale>en</server-locale> <server-last-operation-timestamp>1256716364</server-last-operation-timestamp> <server-port>0</server-port> <server-timeout-normal>120</server-timeout-normal> <server-timeout-long>300</server-timeout-long> <server-timeout-extra-long>1800</server-timeout-extra-long> <server-time-zone/> </server-information>
Version directories for the BMC Remedy AR System adapter

The BMC module contains two version-specific directories version 7.0 and version 7.5. These directories contain subdirectories, organized by namespace, that contain processes to execute commands in BMC Remedy AR System. The BMC module version 7.5 supports all processes for version 7.6. Note If a process for a specific command exists in two directories, you must use the relevant process in the later version directory. For example, if a process for a specific command exists in the version 7.0 and version 7.5 directories, the relevant process contained in the version 7.5 directory must be used to interface with BMC Remedy AR System.
The Version directory lists the following processes: Delete Entry Get Entries Get Schema Insert Entry Query Update Entry Reset Cache Update Entry Batch Insert Items Batch Delete Items Batch Update Items Batch Query Update Items
Delete Entry
The Delete Entry process deletes an entry from a specified BMC Remedy AR System schema. The following table
635
describes the process input parameters for the Delete Entry process.
Process inputs - Delete Entry Process input Description adapter name Specifies the name of the adapter to use for this process Default Value: ARSadapter entry id Identifies the entry to be deleted Yes Required No
schema name Specifies the schema from which the entry should be deleted Yes The following figure shows the XML sample of the input parameters for the Delete Entry process. XML sample for input parameter - requested fields - Delete Entry
<remedy-action> <schema>Sample:Cities</schema> <query>'1'="000000000000009"</query> </remedy-action>
The following figure shows the XML output for the sample Delete Entry process. XML output - requested fields - Delete Entry
<delete-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> </entries> </delete-action-result>
Get Entries
The Get Entries process gets one or more entries from a BMC Remedy AR System schema, satisfying a specified condition. The following table describes the process input parameters for the Get Entries process. Process inputs - Get Entries Process input adapter name schema name requested Description Specifies the name of the adapter to use for this process Required No
Default Value: ARSadapter Specifies the BMC Remedy AR System schema from which the entry should be obtained Yes Specifies the fields to be returned by the query Yes
636
fields match condition
Specifies the query statement to be used to determine the records to be selected This can be a complex condition that includes the key, value variables and operators. For example, a match condition can be: key1 > value1 and key1 < value2 Default Value for key1: value1 Identifies a BMC Remedy AR System field to be evaluated according to the match condition specified Identifies the value that must be present in the key1 field for an entry to be selected, based on the match condition specified Identifies an additional BMC Remedy AR System field to be evaluated according to the match condition specified Note: This input will not be used unless key2 is specifically included in the match condition input. Identifies the value that must be present in the key2 field for an entry to be selected, based on the match condition specified
No
key1 value1 key2
No No No
value2
No
Note: This input will not be used unless value2 is specifically included in the match condition input. download Specifies whether attachment needs to be downloaded with details or only with details in attachments response Valid values: true, false With a value of true the attachments are downloaded on the configured destination location (configurable through adapter configuration) on disk and the attachment details are returned in the response. With a value of false, the attachment details are returned in the response without downloading the attachment to the specified directory. Specifies whether the attachment to be sent in adapter response is a Base 64 encoded retrieve attachment string in response Valid values: true, false (default) With a value of true, the download attachments process input is not considered. This states that the attachment sent in the adapter response is a Base64 encoded string. With a value of false, and download attachments parameter value set to false, the attachment details are shown in response only. The following figure shows an XML sample of the input parameters for the Get Entries process. XML sample for input parameter - requested fields - Get Entries
<request-data> <remedy-action> <schema>Sample:Cities</schema> <query>'Airport Code'="JIA"</query> <fields> <field>City</field> <field>Airport Code</field> </fields> </remedy-action> </request-data>
No
Conditional
637
The following table describes the process output parameters for the Get Entries process. Process outputs - Get Entries Process output Description adapter Specifies the XML document returned by the adapter request executed on the BMC Remedy AR response System Note: The fields returned reflect the fields provided in the requested fields input parameter. The following figure illustrates an XML sample of the output parameters for the Get Entries process. XML sample for output parameter - adapter response - Get Entries
<query-action-result> <entries> <metadata> <entry-count>2</entry-count> </metadata> <entry> <entryid="000000000000179"> <field name="first field name">field value</field> <field name="second field name">field value</field> . . . </entry> <entry> <entryid="000000000000190"> <field name="first field name">field value</field> <field name="second field name">field value</field> . . . </entry> </entries> </query-action-result>
Get Schema
The Get Schema process retrieves the details for a BMC Remedy AR System schema. The following table describes the process input parameters for the Get Schema process.
Process inputs - Get Schema Process input Description adapter name Specifies the name of the adapter to use for this process Default Value: ARSadapter Required No
638
schema name Specifies the schema from which the field information should be obtained Yes The following figure shows the XML sample of the input parameters for the Get Schema process. XML sample for input parameter - requested fields - Get Schema
<remedy-action> <schema>Alert Events</schema> </remedy-action>
The following table describes the process output parameters for the Get Schema process.
Process outputs - Get Schema Process output schema Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Get Schema process. XML sample for output parameter - schema - Get Schema
<schema name="Alert Events"> <metadata> <status>Successfully completed without warnings or errors.</status> <timestamp>1119389568636</timestamp> <field-count>14</field-count> </metadata> <fields> <field name="User" id="2" type="Character string" /> <field name="Status History" id="15" type="Character string" /> <field name="Priority" id="705" type="Integer" /> <field name="Source" id="4" type="Character string" /> <field name="Modified Date" id="6" type="Time" /> <field name="Create Date" id="3" type="Time" /> <field name="Alert Text" id="704" type="Character string" /> <field name="Form" id="701" type="Character string" /> <field name="Request ID" id="1" type="Character string" /> <field name="Server" id="703" type="Character string" /> <field name="Last Modified By" id="5" type="Character string" /> <field name="Read" id="7" type="Enumeration" /> <field name="Request" id="702" type="Character string" /> </fields> </schema>
Insert Entry
639
The Insert Entry process inserts an entry into a BMC Remedy AR System schema. The following table describes the process input parameters for the Insert Entry process. Process inputs - Insert Entry Process Description input adapter Specifies the name of the adapter to use for this process name Default value: ARSAdapter schema Specifies the schema into which an entry will be inserted name field list Specifies the XML document that identifies the fields and values for the entry to be inserted Note: All required fields for a schema record must have values designated to successfully create a new record. In the absence of a value for a required field, the Activity will trigger a compensation and the process log will contain an BMC Remedy AR System API error message. The following figure shows an XML sample of the input parameters for the Insert Entry process. XML sample for input parameter - field list - Insert Entry
<remedy-action> <schema>Sample:Cities</schema> <values> <field name="Airport Code"><![CDATA[CSIA]]></field> <field name="City"><![CDATA[Ohio]]></field> <field name="Attachment1">D:\SrcTestAttachment\uploadthisAttachment.xls</field> </values> </remedy-action>
Required No
Yes Yes
The following table describes the process output parameters for the Insert Entry process.
Process outputs - Insert Entry Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Insert Entry process. XML sample for output parameter - adapter response - Insert Entry
<set-action-result> <entry-id>000000000000179</entry-id> </set-action-result >
640
Query Update Entry

The Query Update Entry process updates a specific record in a BMC Remedy AR System with a given values. The following table describes the process input parameters for the Query Update Entry process.
Process inputs - Query Update Entry Process input adapter name schema name query Description Specifies the name of the adapter to use for this process Default Value: ARSAdapter Specifies the schema in which the entry will be updated Specifies the query to update all the matching records This input is required, if the id is not specified. id Specifies the value to be matched in the specified field id that designates the record to be updated This input is required, if the query is not specified. value field id Specifies the XML document containing the field IDs and corresponding values to be updated in the designated record Specifies the ID of the field to be queried to find a record with a value that matches the value provided for the Id input This input is required, if the id is specified. The following figure shows an XML sample of the input parameters for the Query Update Entry process. XML sample for input parameter - value - Query Update Entry
<remedy-action> <schema>Sample:Cities</schema> <query>'536870914'="CSIA"</query> <value> <field name="City"><![CDATA[MUMBAI]]></field> <field name="Attachment1">D:\SrcTestAttachment\ReplaceAttachment.txt</field> </value> </remedy-action>
Required No
Yes Conditional
Conditional
Yes Conditional
The following table describes the process output parameters for the Query Update Entry process.
Process outputs - Query Update Entry
641
Description specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Query Update Entry process. XML sample for output parameter - adapter response - Query Update Entry
<entries> <metadata> <entry-count>1</entry-count> </metadata> </entries>
Reset Cache
The Reset Cache process refreshes the contents of the adapter cache for the BMC Atrium Orchestrator adapter for BMC Remedy AR System. This is done by clearing the current schema data and reloading new schema data from the BMC Remedy AR System for the schemas specified in the adapter configuration. The following table describes the process input parameters for the Reset Cache process.
Process inputs - Reset Cache Process input Description Required
adapter name Specifies the name of the adapter to use for this process No
Default value: ARSAdapter The following figure illustrates an XML sample of the output parameter for the Reset Cache process. XML sample for input parameter - value - Reset Cache
<request-action>reset-cache</request-action>
The following table describes the output parameters for the Reset Cache process.
Process outputs - Reset Cache Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
642
The following figure illustrates an XML sample of the output parameter for the Reset Cache process. XML sample for output parameter - adapter response - Reset Cache
<reset-cache-action-result> <entries> <metadata> <entry-count>2</entry-count> </metadata> </entries> </reset-cache-action-result>
Update Entry
The Update Entry process updates a specific field in a BMC Remedy AR System record with a given value. The following table describes the process input parameters for the Update Entry process.
Process inputs - Update Entry Process input Description Required No
<adapter name> Specifies the name of the adapter to use for this process Default Value: ARSAdapter <schema name> <entry id> <updated field> <value> Specifies the schema in which the entry will be updated Specifies the ID of the record to be updated Specifies the BMC Remedy AR System field name or field Id of the field to be updated Specifies the value to be placed in the specified field of the designated record
Yes Yes Yes Yes
The following figure shows an XML sample of the input parameters for the Update Entry process. XML sample for input parameter - value - Update Entry
<remedy-action> <schema>Sample:Cities</schema> <entry-id>000000000002893</entry-id> <values> <field name="City"xml:space="preserve">BMC IDD Pune</field> </values> </remedy-action>
The following table describes the process output parameters for the Update Entry process.
Process outputs - Update Entry

643
The following figure illustrates an XML sample of the output parameters for the Update Entry process. XML sample for output parameter - adapter response - Update entry
Note All the v 7.6 processes invoke the v7.5 processes. While executing these processes, you have to mention the version number as v7.6.
Batch Insert Items

The Batch Insert Items process inserts an entry for all items in the XML document into a Remedy datastore. The following table describes the process input parameters for the Batch Insert Items process.
Process inputs - Batch Insert Items Element <adapter name> Description Specifies the name of the adapter to be used by this process as configured in Grid Manager Default value: ARSAdapter <items> Specifies the XML document containing the elements required to insert records into a BMC Remedy AR System schema Note: You must provide values must for each field required by the BMC Remedy AR System to create a complete record. The following figure shows an XML sample of input parameters for the Batch Insert Items process. XML sample for input parameters - Batch Insert Items Yes Required No
644
<items> <item> <schema>Alert Events</schema> <fields> <values> <field id="xxx"></field> <field id="xxx"></field> <field id="xxx"></field> <field id="xxx"></field> <field id="xxx"></field> <field id="xxx"></field> </values> </fields> </item> <items>
The following table describes the process output parameters for the Batch Insert Items process.
Process outputs - Batch Insert Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Batch Insert Items process. XML sample for output parameters - Batch Insert Items
<set-action-result> <entries> <metadata> <entry-count>4</entry-count> </metadata> <entry> <entry-id>xxxx</entry-id> </entry> <entry> <entry-id>xxxx</entry-id> </entry> <entry> <entry-id>xxxx</entry-id> </entry> <entry> <entry-id>xxxx</entry-id> </entry> </entries> </set-action-result>
645
Batch Delete Items

The Batch Delete Items process deletes entries from a Remedy datastore for all items in the XML document. The following table describes the process input parameters for the Batch Delete Items process.
Process inputs - Batch Delete Items Element <adapter name> Description Specifies the name of the adapter to be used by this process as configured in Grid Manager Default value: ARSAdapter <items> Specifies the XML document containing the elements required to delete records from a BMC Remedy AR System schema Note: You must provide values for each field required by the BMC Remedy AR System to delete a complete record. The following figure shows an XML sample of the input parameters for the Batch Delete Items process. XML sample for input parameters - Batch Delete Items
<items> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> </item> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> </item> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> </item> </items>
Required No
Yes
The following table describes the process output parameters for the Batch Delete Items process.
Process outputs - Batch Delete Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Batch Delete Items process.
646
XML sample for output parameters - Batch Delete Items

<delete-action-result> <entries> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> </entries> </delete-action-result>
Batch Update Items

The Batch Update Items process updates a field in a Remedy datastore with a new value for each item in the XML document. The following table describes the process input parameters for the Batch Update Items process.
Process inputs - Batch Update Items Element <adapter name> Description Specifies the name of the adapter to be used by this process as configured in Grid Manager Default value: ARSAdapter <items> Specifies the XML document containing the elements required to update a record for the specified fields in a BMC Remedy AR System schema Note: You must provide values for each field required by the BMC Remedy AR System to update a complete record. The following figure shows an XML sample of the input parameters for the Batch Update Items process. XML sample for input parameter - Batch Update Items Yes Required No
647
<items> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> <updated-field>Request</updated-field> <updated-field-value>Test Request 1</updated-field-value> </item> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> <updated-field>Request</updated-field> <updated-field-value>Test Request 2</updated-field-value> </item> <item> <schema>Alert Events</schema> <entry-id>xxxx</entry-id> <updated-field>Request</updated-field> <updated-field-value>Test Request 3</updated-field-value> </item> </items>
The following table describes the process output parameters for the Batch Update Items process.
Process outputs - Batch Update Items Process output adapter response Description Specifies the XML document returned by the adapter request executed on the BMC Remedy AR System
The following figure illustrates an XML sample of the output parameters for the Batch Update Items process. XML sample for output parameter - Batch Update Items
<update-action-result> <entries> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> <entry> <entry-id>xxxx</entry-id> <entry-count>1</entry-count> </entry> </update-action-result>
648
Batch Query Update Items

The Batch Query Update Items process updates field(s) in a Remedy datastore with a new value for each item in the XML document. The following table describes the process input parameters for the Batch Query Update Items process.
Process inputs - Batch Query Update Items Element Description Required No Yes
<adapter Specifies the name of the adapter to be used by this process as configured in Grid Manager // // Default value: ARSAdapter name> <items> Specifies the XML document containing the elements required to update all records matching the query, for the specified fields in a BMC Remedy AR System schema // // Note: You must provide values for each field required by the BMC Remedy AR System to update a complete record.
The following figure shows an XML sample of the input parameters for the Batch Query Update Items process. XML sample for input parameter - Batch Query Update Items
<items> <item> <field-id>xxx</field-id> <schema>Alert Events</schema> <id>Batch process test-1</id> <fields> <field name="Source"></field> <field name="Request" space="preserve"></field> </fields> </item> <item> <schema>Alert Events</schema> <field-id>Alert Text</field-id> <id>Batch process test-2</id> <fields> <field name="Source"></field> <field name="Request" space="preserve"></field> </fields> </item> </items>
The following table describes the process output parameters for the Batch Query Update Items process.
Process outputs - Batch Query Update Items
649
The following figure illustrates an XML sample of the output parameters for the Batch Update Items process. XML sample for output parameter - Batch Update Items
<query-update-action-result> <entries> <entry> <query>'xxx'="Batch process test-1"</query> <entry-count>yy</entry-count> </entry> <entry> <query>'Alert Text'="Batch process test-2"</query> <entry-count>yy</entry-count> </entry> </entries> </query-update-action-result>
Utilities directory for the BMC Remedy AR System adapter

The Utilities directory contains helper processes that create the XML document used in version-specific processes. Processes are organized into general utilities and sub-directories that correspond to the supported operation types.
Translate Keys to Remedy IDs

The Translate Keys to Remedy IDs process translates variable context keys to BMC Remedy AR System IDs. The following table describes the input parameters for the Translate Keys To Remedy IDs utility.
Process inputs - Translate Keys to Remedy IDs Process input Description Required Yes
mappings Maps internal common element names to BMC Remedy AR System-specific IDs This should be an XML document with a root element named "mappings", which should contain the data required to map an element name to a specified BMC Remedy AR System field name. Maps a BMC Remedy AR System field name its corresponding BMC Remedy AR System query mappings field ID This should be an XML document with a root element named "mappings", which should contain the data required to map an BMC Remedy AR System field name to the corresponding the BMC Remedy AR System field ID. key 1 Specifies the common element name to be translated to the corresponding BMC Remedy AR System field ID
Yes
Yes
650
key 2
Specifies the second common element name to be translated to the corresponding BMC Remedy AR System field ID
No
The following figure shows an XML sample of the input parameters with mappings for the Translate Key To Remedy IDs utility. XML sample for input parameter - mappings - Translate Keys to Remedy IDs
<mappings>  <id type="int">Request ID</id> <submitter type="string">Submitter</submitter> <create-date type="date">Create Date</create-date> <assigned-group type="string">Assigned Group</assigned-group> <last-modified-by type="date">Last Modified By</last-modified-by> <assigned-to type="string">Assigned To</assigned-to> <modified-date type="date">Modified Date</modified-date> <status type="string">Status</status> <short-description type="string">Short Description</short-description> <planned-begin type="string">Planned Begin</planned-begin> <planned-end type="string">Planned End</planned-end> <actual-begin type="string">Actual begin</actual-begin> <actual-end type="string">Actual end</actual-end> <device-name type="string">Device Name</device-name> <ip-address type="string">IP address</ip-address> <customer-name type="string">Customer Name</customer-name> <customer-id type="string">Customer ID</customer-id> <reason type="string">Reason</reason> <associated-ticket-id type="string">TT ID</associated-ticket-id> </mappings>
The following figure shows an XML sample of the input parameters with query mappings for the Translate Key To Remedy IDs utility. XML sample for input parameter - query mappings - Translate Keys to Remedy IDs
<mappings> <mapping <mapping <mapping <mapping <mapping <mapping <mapping <mapping <mapping </mappings>
name="Device Name">536870917</mapping> name="Planned End">536870920</mapping> name="Planned Begin">536870919</mapping> name="IP address">536870926</mapping> name="Customer Name">536870925</mapping> name="Customer ID">536870924</mapping> name="Actual begin">536870921</mapping> name="Actual end">536870922</mapping> name="TT ID">536870927</mapping>
The following table describes the output parameters for the Translate Key To Remedy IDs utility.
651
Process outputs - Translate Keys to Remedy IDs Process output key 1 id key 2 id Description Contains the BMC Remedy AR System field ID that corresponds to the common element name provided in the key1 input Contains the BMC Remedy AR System field ID that corresponds to the common element name provided in the key2 input
Setup Validation directory for the BMC Remedy AR System adapter

These processes facilitate the testing of communication and connectivity to the BMC Remedy AR System application. The processes contained in the SetupValidation sub-directory ensure that the installation and configuration of the application adapter is correct.
Actor adapter requests and responses for the BMC Atrium Orchestrator application adapter for Remedy AR System
The adapter is used to perform actions on BMC Remedy AR System schemas. Each adapter instance is capable of interacting with multiple schemas on a single server. This adapter can be configured using the peer mapping feature, allowing the user to define a configuration to be used for a specific peer's interaction with BMC Remedy AR System. Note Effective with version 7.5.02.03 of BMC Atrium Orchestrator, the BMC Remedy adapter was updated to use pure Java API. The adapter supports the following products: BMC Remedy AR System server 2.0 BMC Remedy AR System server 7.5.00 BMC Remedy AR System Server 7.1.00 BMC Remedy AR System Server 7.0.1
Peer mapping feature

Within the adapter configuration, the user can establish multiple configuration nodes, each referenced by a specific name. These configurations can be mapped to specific peers, allowing each peer to have a specific set of credentials to connect to the BMC Remedy AR System. This is an optional feature and elements pertaining to peer mapping should be omitted from the adapter configuration if this function is not implemented. When using this feature, each peer can be mapped to a specific configuration that will be used for all adapter interaction with BMC Remedy AR System. For peers on which the BMC Atrium Orchestrator adapter for BMC Remedy AR System has been enabled, but a specific mapping has not been established in the adapter configuration, the default configuration (the first configuration node listed in the XML document) will be used.
652
Actor adapter requests for the BMC Atrium Orchestrator application adapter for Remedy AR System
The following table lists the adapter requests:
Actor adapter requests Request action Description
<schema-retrieve> Retrieves a complete list of the field definitions (field name, field ID and data type) for a specified BMC Remedy AR System schema <set> <update> <get> <query> <query-update> <delete> <reset-cache> Adds a new record to a schema Updates specified fields with designated values for a single record in a schema Retrieves the values of designated field names for all records in a specified schema Retrieves the values of designated field names in a specified schema for all rows that satisfy the query criteria Performs a query on a schema, then updates specified fields with designated values for the records contained in the result set of the query Performs a query on a schema, then deletes the rows contained in the result set of the query Clears the adapter's cache of schema metadata When the adapter is invoked again, it will re-create the cache of schema metadata from the current BMC Remedy AR System.
For more information about the adapter requests and responses, see: Adapter request and response with schema-retrieve Adapter request and response with set Adapter request and response with update Adapter request and response with get Adapter request and response with query Adapter request and response with query-update Adapter request and response with delete Adapter request and response with reset-cache Adapter request and response with attachments
Adapter request and response with schema-retrieve

The adapter request with schema-retrieve retrieves a complete list of the field definitions (field name, field ID and data type) for a specified BMC Remedy AR System schema. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the request parameters for the schema-retrieve operation.
Adapter request parameters for schema-retrieve Element Description
653
<schema-retrieve> Retrieves a complete list of the field definitions (field name, field ID and data type) for a specified BMC Remedy AR System schema The following figure shows the sample adapter request for the schema-retrieve operation. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. XML sample request for schema-retrieve
<remedy-action> <schema>Alert Events</schema> </remedy-action>
The adapter response with schema-retrieve contains the field information for the specified schema. The following table describes the parameters for adapter response for the schema-retrieve operation.
Adapter response parameters for schema-retrieve Element Description
<schema-name> Specifies the name of the schema defined in the request. <metadata> <timestamp> Contains the metadata elements returned Specifies the time stamp for the request
<field-count> Specifies the number of fields returned for the requested schema <fields> <field> Contains the field elements returned for the requested schema Specifies the field name, field ID, and data type for the returned field
The following figure shows the XML sample of the response for the schema-retrieve operation. XML sample response for schema-retrieve
654
<schema name="Alert Events"> <metadata> <timestamp>1119389568636</timestamp> <field-count>14</field-count> </metadata> <fields> <field name="User" id="2" type="Character string" /> <field name="Status History" id="15" type="Character string" /> <field name="Priority" id="705" type="Integer" /> <field name="Source" id="4" type="Character string" /> <field name="Modified Date" id="6" type="Time" /> <field name="Create Date" id="3" type="Time" /> <field name="UNUSED" id="8" type="Character string" /> <field name="Alert Text" id="704" type="Character string" /> <field name="Form" id="701" type="Character string" /> <field name="Request ID" id="1" type="Character string" /> <field name="Server" id="703" type="Character string" /> <field name="Last Modified By" id="5" type="Character string" /> <field name="Read" id="7" type="Enumeration" /> <field name="Request" id="702" type="Character string" /> </fields> </schema>
Adapter request and response with set

The adapter request with set adds a new record to a specified BMC Remedy AR System schema. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the elements for adapter request for the set operation.
Adapter request parameters for set Element Description
<schema> Specifies the BMC Remedy AR System schema with which to interact <values> Contains the field values to populate the fields in the new record <field> Specifies the values to be set for the new record The attribute defines the field to be affected for the entry.
Note All required fields for a schema record must have designated values to successfully create a new record. In the absence of a value for a required field, the Activity will trigger a compensation and the process log will contain a BMC Remedy AR System API error.
Note You can provide both a field ID or a field name in the id attribute of the <field> element in the adapter request.
655
The following figure shows a sample adapter request for the set operation when the id attribute of the <field> element is a field ID. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. XML sample request for set when < field > element uses a field ID
<remedy-action> <schema>Alert Events</schema> <values> <field id="704"> Test with field ID</field> <field id="4">Rohit-Junit</field> <field id="701">Alert Events</field> <field id="702">Remedy Actor Adapter</field> <field id="703">Local Host</field> <field id="2">Demo</field> </values> </remedy-action>
The following figure shows a sample adapter request for the set operation when the id attribute of the <field> element is a field name. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. XML sample request for set when < field > element uses a field name
<remedy-action> <schema>Alert Events</schema> <values> <field id="Alert Text">Test with field name</field> <field id="Source">Rohit-Junit</field> <field id="Form">Alert Events</field> <field id="Request">Remedy Actor Adapter</field> <field id="Server">Local Host</field> <field id="User">Demo</field> </values> </remedy-action>
The adapter response with set returns an adapter response that contains the entry ID for the new record added to the specified schema in the adapter request. The following figure shows the XML sample for the adapter response for the set operation. Adapter response for set
<set-action-result> <entry-id>000000000000179</entry-id> </set-action-result>
Adapter request and response with update
656
The adapter request with update updates specified fields with designated values for a single record in a schema. The record is identified by the entry ID from BMC Remedy AR System. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the parameters for adapter request for the update operation.
Adapter request parameters for update Element <schema> Description Specifies the BMC Remedy AR System schema with which to interact
<entry-id> Specifies the value for the row to be updated <values> <field> Contains the field values for one or more fields to be updated Specifies the values to be updated for the entries in the result set of the query The attribute defines the field to be updated for the entry.
Note You can provide both a field ID or a field name in the id attribute of the <field> element in the adapter request.
The following figure shows the sample adapter request for the update operation when the id attribute of the <field> element is a field ID. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Adapter request for update when < field > element uses a field ID
<remedy-action> <schema>Alert Events</schema> <entry-id>000000000354710</entry-id> <values> <field id="704">Updated text with field ID specified.</field> </values> </remedy-action>
The following figure shows a sample adapter request for the update operation when the id attribute of the <field> element is a field name. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. XML sample request for update when < field > element uses a field name
657
<remedy-action> <schema>Alert Events</schema> <entry-id>000000000354710</entry-id> <values> <field id="Alert Text">Updated text with field name </values> </remedy-action>
specified.</field>
The adapter response with update returns an adapter response that contains the number of entries updated. The following table describes the parameters for the adapter response for the update operation.
Adapter response parameters for update Element <entries> <metadata> Description Contains the entry fields returned by the action Contains the metadata from the request
<entry-count> Specifies the number of entries updated The following figure shows the XML sample of the adapter response for the update operation. Adapter response for update
Adapter request and response with get

The adapter request with get retrieves the values of designated field names for all records in a specified BMC Remedy AR System schema. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the elements for the adapter request for the get operation.
Adapter request parameters for get Element Description
<schema> Specifies the BMC Remedy AR System schema with which to interact <fields> Contains the field names <field> Specifies the field names for which values will be retrieved from the schema
658
The following figure shows a sample adapter request for the get operation. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Adapter request for get
<remedy-action> <schema>Alert Events</schema> <fields> <field>User</field> <field>Priority</field> <field>Request ID</field> </fields> </remedy-action>
The adapter response with get returns an adapter response that contains values for the fields specified in the request for every row in the requested schema. The following table describes the parameters for the adapter response for the get operation.
Adapter response parameters for get Element < entries> <metadata> Description Contains the entry fields returned by the query Contains the metadata from the request
<entry-count> Specifies the number of entries returned by the query <entry> <field> Contains values returned by the query Specifies the field name and corresponding data value for the fields queried for the specific entry ID
The following figure shows the XML sample of the adapter response for the get operation. Adapter response for get
659
<get-action-result> <entries> <metadata> <entry-count>6</entry-count> </metadata> <entry id="000000000000152"> <field name="User">Justin</field> <field name="Priority">2</field> <field name="Request ID">000000000000152</field> </entry> <entry id="000000000000153"> <field name="User">Sharon</field <field name="Priority">9</field> <field name="Request ID">000000000000153</field> </entry> <entry id="000000000000155"> <field name="User">Ted</field> <field name="Priority">1</field> <field name="Request ID">000000000000155</field> </entry> <entry id="000000000000156"> <field name="User">Sharon</field> <field name="Priority">3</field> <field name="Request ID">000000000000156</field> </entry> <entry id="000000000000158"> <field name="User">Ted</field> <field name="Priority">8</field> <field name="Request ID">000000000000158</field> </entry> <entry id="000000000000161"> <field name="User">Sharon</field> <field name="Priority">2</field> <field name="Request ID">000000000000161</field> </entry> </entries> </get-action-result>
Adapter request and response with query

The adapter request with query retrieves the values of designated field names in a specified BMC Remedy AR System schema for all rows that satisfy the query criteria. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the parameters for the adapter request for the query operation.
Adapter request parameters for query Element Description
660
<schema> Specifies the BMC Remedy AR System schema with which to interact <fields> Contains the field names <field> <query> Specifies field names to be retrieved from the schema Specifies the query to be executed on the schema The BMC Remedy AR System schema's numeric field IDs are used to identify the fields in the query. Field ID's are enclosed in ' ' (single quotes), string values are enclosed in " " (double quotes), and numeric values do not need to be enclosed. The query should be wrapped in CDATA to prevent any issues with XML parsing.
The following figure shows a sample adapter request for the query operation. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Adapter sample request for the query operation
<remedy-action> <schema>Alert Events</schema> <fields> <field>Priority</field> <field>User</field> <field>Request ID</field> <field>Attachment</field> <field>Attach2</field> </fields> <query><![CDATA['2'="Sharon" and '705'<3]]></query> </remedy-action>
The following figure shows a sample adapter request for the query operation when the value of a <field> element is specified as both a field ID and a field name in the adapter request. XML sample of adapter request for the query operation with both field ID and field name
<remedy-action> <schema>Alert Events</schema> <query>'1'="000000000354720"</query> <fields> <field>2</field> <field>1</field> <field>Alert Text</field> </fields> </remedy-action>
The adapter response to a request with query operation is a response that contains fields retrieved in the query by the adapter request. The following table describes the adapter response elements for the query operation.
Adapter response parameters for query Element Description
661
<entries> <metadata>
Contains the entry fields returned by the query Contains the metadata from the request
<entry-count> Specifies the number of entries returned by the query <entry> <field> Contains values returned by the query, the attribute displays the row ID for the entry Specifies the value for the fields queried that is specific to the row ID for the entry
The following figure shows the XML sample of the adapter response for the query operation. Adapter response for query
<query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000000161"> <field name="User">Sharon</field> <field name="Priority">2</field> <field name="Request ID">000000000000161</field> <field name="Attachment"> <filename-in-remedy>D:\SrcTestAttachment\ attachedfileinRemedy.txt</filename-in-remedy> <file-location>hostname:D:\configuredDestinationDirectorypath \attachedfileinRemedy.txt</file-location> </field> <field name="Attach2"/> </entry> </entries> </query-action-result>
The following figure shows the XML sample of the adapter response for the query operation when the <query-response-contains-id-or-name> element is set to ID in the adapter configuration. In this example, the field ID is returned as a value of the name attribute in the adapter response. In this case, the value does not depend on whether a field ID or a field name is specified in the adapter request, because the <query-response-contains-id-or-name> element is set to ID in the adapter configuration. XML sample of the adapter response when < query-response-contains-id-or-name > is set to ID in the adapter configuration
662
<adapter-response> <execution-duration>97238</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000354720"> <field name="1">000000000354720</field> <field name="2">Demo</field> <field name="704">Test with field names</field> </entry> </entries> </query-action-result> </data> </adapter-response>
The following figure shows the XML sample of the adapter response for the query operation when the <query-response-contains-id-or-name> element is set to name in the adapter configuration. In this example, the field name is returned as a value of the name attribute in the adapter response. In this case, the value does not depend on whether a field ID or a field name is specified in the adapter request, because the <query-response-contains-id-or-name> element is set to name in the adapter configuration. XML sample of the adapter response when < query-response-contains-id-or-name > is set to name in the adapter configuration
<adapter-response> <execution-duration>97238</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000354720"> <field name="Request ID">000000000354720</field> <field name="User">Demo</field> <field name="Alert Text">Test with field names</field> </entry> </entries> </query-action-result> </data> </adapter-response>
663
Note If you do not specify any value or an invalid value for the <query-response-contains-id-or-name> element in the adapter configuration, the adapter response contains the value that you specify for the <field> element in the adapter request.
The following figure shows an XML sample of the adapter response for the adapter request shown in the following figure: When you do not specify any value or specify an invalid value for the <query-response-contains-id-or-name> element in the adapter configuration, and Both field ID and field name are specified in the adapter request
XML sample of the adapter response when < query-response-contains-id-or-name > is invalid or not specified in the adapter configuration
<adapter-response> <execution-duration>97238</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000354720"> <field name="1">000000000354720</field> <field name="2">Demo</field> <field name="Alert Text">Test with field names</field> </entry> </entries> </query-action-result> </data> </adapter-response>
Adapter request and response with query-update

The adapter request with query-update performs a query on a BMC Remedy AR System schema, and then updates specified fields with designated values for the records contained in the result set of the query. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the parameters for the adapter request for the query-update operation.
Adapter request parameters for query-update
664
Element <query>
Description Specifies the query to be executed on the schema The numeric Field ID's are used to identify the fields in the query. Field ID's are enclosed in ' ', String values are enclosed in " " and numeric values do not need to be enclosed. The query should be wrapped in CDATA to prevent any issues with XML parsing.
<schema> Specifies the BMC Remedy AR System schema with which to interact <values> Contains the field values for the fields to be updated <field> Specifies the field ID and corresponding data value for the fields queried for the specific entry ID
The following figure shows a sample adapter request for the query-update operation. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Adapter request for query-update
<remedy-action> <query><![CDATA['4'="CEO"]]></query> <schema>Alert Events</schema> <values> <field id="705">1</field> </values> </remedy-action>
The adapter response with query-update returns an adapter response with a count of the number of records updated by the query. The following table describes the parameters for the adapter response for query-update.
Adapter response parameters for query-update Element <entries> <metadata> Description Contains the entry fields returned by the query Contains the metadata from the request
<entry-count> Specifies the number of entries returned by the query The following figure shows the XML sample of the adapter response for the query-update operation. Adapter response for query-update
<query-update-action-result> <entries> <metadata> <entry-count>8</entry-count> </metadata> </entries> </query-update-action-result>
665
Adapter request and response with delete

The adapter request with delete performs a query on a BMC Remedy AR System schema, and then deletes the rows contained in the result set of the query. This action is typically reserved for non-trouble ticketing-related schema. It would be used for schemas related to asset management or other such functions. When you create the adapter request in the Transform Editor, you must enclose this adapter request within <request-data> tags. The following table describes the parameters for the adapter request for the delete operation.
Adapter request parameters for delete Element Description
<schema> Specifies the BMC Remedy AR System schema with which to interact <query> Specifies the query to be executed on the schema The rows in the result set of the query will be deleted. The BMC Remedy AR System schema's numeric Field ID's are used to identify the fields in the query. Field ID's are enclosed in ' ', String values are enclosed in " " and numeric values do not need to be enclosed. The query should be wrapped in CDATA to prevent any issues with XML parsing. The following figure shows a sample adapter request for the delete operation. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Adapter request for delete
<remedy-action> <schema>Sample:Cities</schema> <query>'1'="000000000000009"</query> </remedy-action>
The adapter response with delete returns an adapter response that contains the number of entries deleted. The following table describes the parameters for the adapter response for the delete operation.
Adapter response parameters for delete Element <entries> <metadata> Description Contains the entry fields returned by the action Contains the metadata from the request
<entry-count> Specifies the number of entries deleted The following figure shows the XML sample of the adapter response for the delete operation. Adapter response for delete
666
<remedy-action> <schema>User</schema> <query><![CDATA['101'="Joan"]]></query> </remedy-action>
Adapter request and response with reset-cache

The adapter response with reset-cache clears the adapter's cache of BMC Remedy AR System schema metadata. The next time the adapter is called, it will re-create the cache of schema metadata in BMC Atrium Orchestrator from the current BMC Remedy AR System. This should be done on a regular schedule to ensure that updated BMC Remedy AR System schema data is being used in BMC Atrium Orchestrator. Note The reset-cache action does not require XML text in the adapter Data field on the Properties tab of the Property Panel for the Call adapter Activity.
The adapter response with reset-cache returns an adapter response that contains the number of schemas refreshed. The following table describes the parameters for the adapter response for the reset-cache operation.
Adapter response parameters for reset-cache Element <entries> <metadata> Description Contains the entry fields returned by the action Contains the metadata from the request
<entry-count> Specifies the number of entries deleted The following figure shows the XML sample of the adapter response for the reset-cache operation. Adapter response for reset-cache
<remedy-action> <schema>User</schema> <query><![CDATA['101'="Joan"]]></query> </remedy-action>
Adapter request and response with attachments

The following figure illustrates an XML sample of the BMC Remedy AR System adapter request that has attachments. Adapter request for request that has attachments
667
<remedy-action> <download-attachments>false</download-attachments> <retrieve-attachment-in-response>false</retrieve-attachment-in-response> <schema>SchemaAttachment</schema> <query>'1'="000000000000003"</query> <fields> <field>Submitter</field> <field>Attachment1</field> <field>Attachment2</field> </fields> </remedy-action>
The following figure illustrates an XML sample of the BMC Remedy AR System adapter response when <download-attachments> is false and <retrieve-attachment-in-response> is false. Adapter response if < download-attachments > is false and < retrieve-attachment-in-response > is false
<query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000000003"> <field name="Submitter">Remedy test action show only attachment details</field> <field name="Attachment1"> <filename-in-remedy>D:\SrcTestAttachment\testAttach.doc</filename-inremedy> </field> <field name="Attachment2"> <filename-in-remedy>D:\SrcTestAttachment\testSpreadSheet.xls</filename-inremedy> </field> </entry> </entries> </query-action-result>
The following figure illustrates an XML sample of the BMC Remedy AR System adapter response when <download-attachments> is true and <retrieve-attachment-in-response> is false. Adapter response if <download-attachments > is true and < retrieve-attachment-in-response > is false
668
<query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000000003"> <field name="Submitter">Remedy test action show only attachment details</field> <field name="Attachment1"> <filename-in-remedy>D:\SrcTestAttachment\testAttach.doc</filename-inremedy> <file-location>dbhola-lt-01:D:\temp\remedy\testAttach.doc</file-location> </field> <field name="Attachment2"> <filename-in-remedy>D:\SrcTestAttachment\testSpreadSheet.xls</filename-inremedy> <file-location>dbhola-lt-01:D:\temp\remedy\testSpreadSheet.xls</filelocation> </field> </entry> </entries> </query-action-result>
The following figure illustrates an XML sample of the BMC Remedy AR System adapter response when <download-attachments> is true or false and <retrieve-attachment-in-response> is {true}}. Adapter response if < download-attachments > is true or false and < retrieve-attachment-in-response > is true
<query-action-result> <entries> <metadata> <entry-count>1</entry-count> </metadata> <entry id="000000000000003"> <field name="Attachment1"> <filename-in-remedy>D:\SrcTestAttachment\testAttach.doc</filename-inremedy> <attachment-data>This is a sample of attachments1.</attachment-data> </field> <field name="Attachment2"> <filename-in-remedy>D:\SrcTestAttachment\testSpreadSheet.xls</filename-inremedy> <attachment-data>This is a sample of attachments2.</attachment-data> </field> </entry> </entries> </query-action-result>
BMC Remedy AR System monitor adapter

669
A monitor adapter obtains data from an external system and generates an event message. Depending on the monitor adapter, it can obtain data by: Pulling data from an external system by polling the system Receiving data that is pushed from an external system The event is evaluated by rules and can trigger specific workflow processes when the rule criteria are met. The BMC Remedy AR System monitor adapter captures an alert that is created in the BMC Remedy AR System application and generates an event message. This adapter is responsible for handling alerts generated through Notify Filters that have been configured in the BMC Remedy AR System. This adapter does not support multiple configurations, but multiple monitor adapters can be created in the Grid Manager, with each monitor adapter having an unique configuration. Note If multiple monitor adapters are created in Grid Manager, each configuration must use unique credentials.
Configure a Notify Filter in BMC Remedy AR System

A Notify Filter is configured using the Remedy Administrator within the BMC Remedy AR System. This filter will send a message through the BMC Remedy AR System API to the monitor adapter when a selected action is executed on a designated form. 1. Using the Remedy Administrator in the BMC Remedy AR System, add a new filter. This filter can be named using any valid name for an BMC Remedy AR System filter. 2. Associate the Filter with a form name. 3. Set the values for the Execute On field. An alert will be generated for each of the selected actions executed on the designated form. 4. On the If Action tab, set the New Action field value to Notify. 5. In the Notify section of the If Action tab, enter the desired notification text in the text field. This text will populate the <text> element of the monitor adapter event and can be used as a condition in BMC Atrium Orchestrator Development Studio Rules Editor. 6. The user name should be set to an existing user in the BMC Remedy AR System. This user will also be defined in the <user-name> element of the monitor adapter configuration. 7. Set the Mechanism value to Alert. 8. Save the Filter. With the filter configured in the BMC Remedy AR System, the BMC Remedy AR System API will generate alerts received by the BMC Atrium Orchestrator monitor adapter for BMC Remedy AR System and will be evaluated by active rules.
Adapter event for the BMC Remedy AR System monitor adapter

The following table shows the adapter event elements for the BMC Remedy AR System monitor adapter.
Adapter event elements for monitor adapter Data elements <alert-id> Description Specifies the alert ID generated by the BMC Remedy AR System Server
<server-name> Specifies the name of the server that generated the alert
670
<form-name> <object-id> <source> <timestamp> <priority> <text>
Specifies the name of the form the alert for which the alert was generated Specifies the object ID of the event Specifies the source of the event Specifies the timestamp of when the event occurred Specifies the priority assigned to the event Specifies any text associated with the event
Note To use the data from the adapter event in the triggered process, a job input parameter named inputevent should be created on the Start Activity of the process. The <data> element from the adapter event will automatically populate this input.
The following figure shows the XML template for the adapter event. XML template for adapter event
<alert-message alert-id=" 000000000007410"> <server-name>server1</server-name> <form-name/> <object-id/> <source>Sharon</source> <timestamp> 1126541703</timestamp> <priority>1</priority> <text>alert message text</text> </alert-message>
BMC Atrium Orchestrator Application Adapter for Solaris Zones

An Oracle Solaris Zone is a complete runtime environment for an application. Each Solaris Zone enables you to isolate an application component but share a single instance of the Solaris operating system with other Zones. Solaris Zones enables you to allocate resources, such as CPU, physical memory, and network bandwidth, based on workload and business conditions. The BMC Atrium Orchestrator application adapter for Solaris Zones contains an actor adapter and an adapter module. The adapter module comprises workflow processes that perform the standard application operations available through the SSH Application Programming Interface (API) on Solaris. To execute operations, the application adapter invokes SSH API calls on the Solaris host. The actor adapter enables you to perform the following categories of operations in Solaris Zones: Basic Zone operations Advanced Zone operations Configure Zone operations
671
Supported version of Solaris

The adapter supports Solaris version 10 Update 4 or later.
Configuring the BMC Atrium Orchestrator Application Adapter for Solaris Zones
You can create an adapter in Grid Manager by defining a configuration. This configuration provides information about how BMC Atrium Orchestrator interacts with Solaris Zones. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. Note The default name for the actor adapter is SolarisZoneActorAdapter.
To create an actor adapter configuration

1. Log on to the BMC Atrium Orchestrator Grid Manager. 2. To access the adapters page, click the Manage tab; then click the Adapters tab. 3. On the Adapters in Repository page, select the check box corresponding to bmc-adapter-solaris-zones-actor. 4. Click Add to Grid to include the adapter in the Adapters on Grid list. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to Step 7 to configure the adapter using the XML view: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Under Properties, enter or select values for the configuration elements. The configuration elements for the adapter are described in the following table. Include all required elements indicated with an asterisk (*). d. Click OK. 7. (optional) Configure the adapter in the XML view using the following substeps: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Click Switch to XML View. d. On the Warning message that appears, click Switch View. e. In the Properties text box, enter the adapter configuration properties in XML format, including all required elements. XML sample for configuring the actor adapter
672
<config> <target>vm-sol-abc</target> <user-name>admin</user-name> <password encryption type ="Plain">admin1</password> <port>9080</port> <prompt>#</prompt> <timeout-secs>60</timeout-secs> <known-hosts-config>admin/ssh/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-rsa</preferred-pk-algorithm> <establish-connection-timeout-secs>100 </establish-connection-timeout-secs> <network-environment>true</network-environment> <line-termination>&#A;</line-termination> </config>
f. Click OK. g. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list. The following table describes the adapter configuration elements and attributes that you can specify using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the _UI label_column. Note Switching to the XML view to specify configuration elements and attributes means that you cannot thereafter use the form for modifying the adapter configuration.
Node elements and attributes required to configure the actor adapter UI Label Target Element <target> Description Specifies the Solaris computer on which the Global Zone is running Specifies the user name for authentication on the Solaris computer Required Yes
User Name
<user-nam>
Yes
Password
<password>
Specifies the password No corresponding to the specified user-name
673
Encryption Type
<encryption-type>
Indicates whether the password specified is encrypted; is an attribute of the <password> element, not an element itself Valid values: Base64, Plain (default) Specifies the SSH port on which the SSH service is running on the Solaris computer
No
Port
<port>
No
Private Key File
<private-key-file>
Specifies the path and file Conditional name of the local SSH key file Required if the password element The path and file must exist is not specified. If on the peer where the adapter both the password is enabled. and the private-key-file element are specified, the private-key-file element is used and the password is ignored Specifies the pass phrase Conditional used to protect the private key Required if the file private-key-file element is specified. Indicates whether the pass phrase specified is encrypted; is an attribute of the <pass-phrase> element, not an element itself Valid values: Base64, Plain (default) Specifies the console prompt displayed when the Solaris computer is waiting for a command This element contains the terminating string, typically ending with a $, >, or # character. Each command executes in a separate session, as if each command is executing in a new command shell. The prompt indicates the completion of the command execution. The prompt element must be unique, and it should not match the potential command output to avoid parsing issues. No
Pass Phrase
<pass-phrase>
Encryption Type
<encryption-type>
Prompt
<prompt>
Conditional Required for using the proxy command feature
674
Timeout Secs
<timeout-secs>
Specifies the time, in No seconds, to wait for the expected prompt to be returned by the Solaris computer If the expected prompt is not returned before the specified value in the element has elapsed, an error message is returned. The default value for this element is 60 seconds. Specifies the location of the No local known_hosts file The known_hosts file is used to perform key verification. The default value for this element is home_dir/.ssh/known_hosts . Indicates whether a connection should continue if the key verification process fails The valid values for this element are: true = (default) adapter maintains the connection to an unknown or mismatched system false = adapter terminates the connection to an unknown or mismatched system and returns an error in the adapter response No
Known Hosts Config
<known-hosts-config>
Allow Unknown Hosts
<allow-unknown-hosts>
Preffered Pk <preferred-pkalgorithm> Algorithm
Specifies the algorithm for encrypting the public key The valid values for this element are: ssh-dss ssh-rsa (default)
No
675
Establish Connection Timeout Secs
<establish-connection-timeout-secs> Specifies the time, in No seconds, to wait for user authentication on the Solaris server If the authentication process is not successful within this interval, the adapter returns an error message. The default value for this element is 60 seconds. Creates an extra channel session for use with Oracle Solaris 9 The valid values for this element are: true false (default) To connect to network devices, you must set this element to false. No
Network <network-environment> Environment
Line Termination
<line-termination>
Specifies the line termination No character used with the SSH command The value for this element is hexadecimal. For example, the hexadecimal value for \r is &#D and for{{\n}} is &#A;. If you do not specify this element, the adapter does not assign any line termination character.
BMC Atrium Orchestrator Application Adapter for Solaris Zones module

Each operation supported by the application adapter has a corresponding process in the adapter module. Top-level processes perform high-level functions and call specialized processes in subdirectories of the version directory. Each subdirectory contains process directories that correspond to the operation type for that operation.
Top-level processes for the BMC Atrium Orchestrator Application Adapter for Solaris Zones
The top-level processes perform high-level functions and call specialized processes in the subdirectories of the version 10.4 directory. The top-level processes in the Project Explorer window execute the following Solaris Zones processes: Create Items Find Items Perform Operations Update Items The top-level processes use the following inputs:
676
adapter name - This optional element specifies the name of the adapter that handles the adapter request. The default adapter name is SolarisZoneActorAdapter. zone name - This required element specifies the Zone name on which the adapter operation is performed. items - This optional element contains the Items XML used to perform an operation in Solaris Zones. item type - This required element specifies the relevant item type for the process to be executed. version - This required element specifies the version of the Solaris OS. Solaris 10.4 or later are supported. connection parameters - This optional element contains the XML specifying the connection data for the adapter to connect to the target. operation timeout - This optional element specifies the time, in seconds, to wait for an operation to execute on the Solaris server. If the operation is not successful within the specified interval, the adapter returns an error message. The default value for this element is 300 seconds.
SetupValidation directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones
The processes in the SetupValidation directory contain sample values for the request elements. You can quickly change these sample values to reflect the values in your environment. A process is provided to test each supported method of executing operations in Solaris Zones.
Utilities directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones
The functional processes require complex XML inputs. You can generate these complex XML inputs by using the constructor processes in the Utilities directory.
v10.4 directory for the BMC Atrium Orchestrator Application Adapter for Solaris Zones
The v10.4 directory contains functional processes specific to Solaris Zones. A process is available for each supported operation. Processes are grouped in subdirectories based on the type of the operation. The following table shows the mapping between wrapper processes and operation names. Mapping between wrapper processes and operation names Wrapper name Basic Zone operations Boot Zone Reboot Zone Install Zone Uninstall Zone Halt Zone Ready Zone Advanced Zone operations Move Zone Configure Zone operations Move_Zone Boot_Zone Reboot_Zone Install_Zone Uninstall_Zone Halt_Zone Ready_Zone Operation name
677
Create Zone
Create_Zone
Create Zone With Custom Settings Create_Zone_With_Custom_Settings Create Zone From Template Clone Zone Delete Zone Retrieve Zone Configuration Update Zone Configuration Create_Zone_From_Template Clone_Zone Delete_Zone Retrieve_Zone_Configuration Update_Zone_Configuration
Actor adapter requests and responses for the BMC Atrium Orchestrator Application Adapter for Solaris Zones
The adapter requests for the actor adapter use a set of elements to invoke an SSH API call on the Solaris computer. The set of elements used to make an API call is referred to as an operation. You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity. The actor adapter can perform the following categories of operations: Basic Zone operations Advanced Zone operations Configure Zone operations The actor adapter supports the operations that are categorized and described in the following table: Adapter operations Type Basic Zone operations Basic Zone operations Basic Zone operations Basic Zone operations Basic Zone operations Process name Boot Zone Reboot Zone Install Zone Description Boots the specified Zone, only if the Zone is in the halted or installed state Reboots the specified Zone, only if the Zone is in the running state Installs the Zone operating system files in the specified zone path This operation also changes the state of the Zone from the configured state to the installed state. Uninstalls all files under the root file system of the specified Zone This operation also changes the state of the Zone from the installed state to the configured state. Removes the application environment and the virtual platform for the specified Zone This operation also changes the state of the Zone from the running state to the installed state. Changes the state of the specified Zone to ready and prepares the virtual platform to initiate the execution of user processes
Uninstall Zone
Halt Zone
Basic Zone operations
Ready Zone
678
Advanced Zone operations Configure Zone operations Configure Zone operations Configure Zone operations Configure Zone operations Configure Zone operations Configure Zone operations Configure Zone operations
Move Zone
Moves the Zone to the specified location on the same Solaris host computer, by changing the zone path For this operation to execute, the Zone must be in the halted state. Creates a new Zone with the basic parameters
Create Zone
Create Zone With Custom Settings Create Zone From Template Clone Zone
Creates a new Zone with advanced configuration options This operation enables you to add virtual devices, such as a virtual hard disk or a virtual ethernet card, while creating the Zone. Creates a new Zone by using the specified Zone template The template must exist on the local Solaris host. Creates a new Zone on a Solaris host computer by copying the Zone data from a source zone path to a target zone path You can perform the Clone Zone operation only for Zones in the installed or running state. Deletes the specified Zone
Delete Zone
Retrieve Zone Configuration Update Zone Configuration
Retrieves the configuration parameters of the specified Zone
Updates one or more configuration parameters of the specified Zone This operation enables you to add or remove hard disks, CD-ROMs, or ethernet adapters from a Zone.
Note The <user-name> that you specify for any operation must have the superuser role.
Adapter requests and responses for the Basic Zone operations

This section describes the adapter requests and responses for the Basic Zone operations. The Basic Zone operations are: Boot Zone Reboot Zone Install Zone Uninstall Zone Halt Zone Ready Zone Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Request and response for the Boot Zone operation

The Boot Zone operation enables you to boot the specified Zone, which must be in the installed or the halted state. The following table describes the elements for the adapter request:
679
Adapter request elements for the Boot Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone Defines the name of operation: Boot_Zone Specifies the name of the Zone that you want to boot Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
<operation-timeout-secs> Specifies the time, in seconds, to wait for the operation to complete on the target server If the operation is not successful within this interval, the adapter returns an error message. Default value: 300 seconds <user-name> Specifies the user name for the Solaris computer If no user name is specified, the request is executed with the user name specified in the adapter configuration. Specifies the password corresponding to the user name
No
No
<password>
Conditional Required if you specify the <user-name> element
The following figure shows the sample adapter request for the Boot Zone operation: Sample adapter request for the Boot Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc</host> <user-name>admin</user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Boot_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
Note You need to specify the elements in the <target> block of the adapter request only if you want to override the elements specified in the adapter configuration.
680
The following figure shows the response for the sample adapter request: Sample adapter response for the Boot Zone operation
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone boot</command> <line-count>1</line-count> <execution-milliseconds>547</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Boot_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Reboot Zone operation

The Reboot Zone operation enables you to reboot the specified Zone, which must be in the running state. The following table describes the elements for the adapter request: Adapter request elements for the Reboot Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone. Defines the name of operation: Reboot_Zone Specifies the name of the Zone that you want to reboot Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
681
No
No
<password>
The following figure shows the sample adapter request for the Reboot Zone operation: Sample adapter request for the Reboot Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc</host> <user-name>admin</user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Reboot_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Reboot Zone operation
682
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone reboot</command> <line-count>1</line-count> <execution-milliseconds>2062</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Reboot_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Install Zone operation

The Install Zone operation enables you to install the Zone operating-system files to the specified zone path. This operation changes the state of the Zone from the configured state to the installed state. The following table describes the elements for the adapter request: Adapter request elements for the Install Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone Defines the name of operation: Install_Zone Specifies the name of the Zone that you want to install Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
<operation-timeout-secs> Specifies the time, in seconds, to wait for the operation to complete on the target server If the operation is not successful within this interval, the adapter returns an error message. Default value: 300 seconds
No
683
<user-name>
Specifies the user name for the Solaris computer If no user name is specified, the request is executed with the user name specified in the adapter configuration. Specifies the password corresponding to the user name
No
<password>
The following figure shows the sample adapter request for the Install Zone operation: Sample adapter request for the Install Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc</host> <user-name>admin</user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Install_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Install Zone operation
684
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone install</command> <line-count>1</line-count> <execution-milliseconds>1750</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Install_Zone installed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Uninstall Zone operation

The Uninstall Zone operation enables you to uninstall all files under the root file system of the specified Zone. This operation also changes the state of the Zone from the installed state to the configured state. The following table describes the elements for the adapter request: Adapter request elements for the Uninstall Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone Defines the name of operation: Uninstall_Zone Specifies the name of the Zone that you want to uninstall Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
No
685
<user-name>
No
<password>
The following figure shows the sample adapter request for the Uninstall Zone operation: Sample adapter request for the Uninstall Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Uninstall_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Uninstall Zone operation
686
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone uninstall</command> <line-count>1</line-count> <execution-milliseconds>1220</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Uninstall_Zone executed successfully!!</line> </output> </operation-output> </target-output> </target-output> </solaris-zones-response>
Request and response for the Halt Zone operation

The Halt Zone operation removes the application environment and the virtual platform for the specified Zone. This operation also changes the state of the Zone from the running state to the installed state. The following table describes the elements for the adapter request: Adapter request elements for the Halt Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone Defines the name of operation: Halt_Zone Specifies the name of the Zone that you want to halt Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
No
687
<user-name>
No
<password>
The following figure shows the sample adapter request for the Halt Zone operation: Sample adapter request for the Halt Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Halt_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Halt Zone operation
688
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone halt</command> <line-count>1</line-count> <execution-milliseconds>1718</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Halt_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Ready Zone operation

The Ready Zone operation enables you to transition the specified Zone into the ready state and prepare the virtual platform for executing user processes. The following table describes the elements for the adapter request: Adapter request elements for the Ready Zone operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Defines the type of operation: Basic_Zone Defines the name of operation: Ready_Zone Specifies the name of the Zone that you want to transition to the ready state Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
No
689
<user-name>
No
<password>
The following figure shows the sample adapter request for the Ready Zone operation: Sample adapter request for the Ready Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Basic_Zone</operation-type> <operation-name>Ready_Zone</operation-name> <operation-timeout-secs>100</operation-timeout-secs> <zone-name>testzone</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Ready Zone operation
690
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z testzone ready</command> <line-count>1</line-count> <execution-milliseconds>547</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Ready_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Adapter request and response for the Advanced Zone operation

This section describes the adapter request and response for the Advanced Zone operation. Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
Adapter request and response for the Advanced Zone operation

The Move Zone operation, the only operation in the Advanced Zone category, enables you to move a Zone to a new location by specifying the new zone path. The following figure shows an <items> XML template for the Move Zone operation: <items> XML template for the Move Zone operation
<items> <item> <parameters> <new-zone-path></new-zone-path> </parameters> </item> </items>
The following table describes the elements for the adapter request:
691
Adapter request elements for the Move Zone operation Element <operation-type> <operation-name> <zone-name> <new-zone-path> <host> <port> Definition Defines the type of operation: Advanced_Zone Defines the name of operation: Move_Zone Specifies the name of the Zone that you want to move Specifies the new zone path for the Zone Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes Yes No No
No
No
<password>
The following figure shows the sample adapter request for the Move Zone operation: Sample adapter request for the Move Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Advanced_Zone</operation-type> <operation-name>Move_Zone</operation-name> <operation-timeout-secs>300</operation-timeout-secs> <zone-name>testzone</zone-name> <parameters> <new-zone-path>/zones/samplezone</new-zone-path> </parameters> </solaris-zones-request>
692
The following figure shows the response for the sample adapter request: Sample adapter response for the Move Zone operation
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z "testzone" halt; zoneadm -z "testzone" move "/zones/samplezone"</command> <line-count>1</line-count> <execution-milliseconds>4258</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Move_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Adapter requests and responses for the Configure Zone operations

This section describes the actor adapter requests and responses for the Configure Zone operations. The Configure Zone operations are: Create Zone Create Zone With Custom Settings Create Zone From Template Clone Zone Retrieve Zone Configuration Update Zone Configuration Delete Zone Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.
693
Request and response for the Create Zone operation

The Create Zone operation enables you to create a Zone by specifying only the required parameters for the Zone. The following figure shows an <items> XML template for the Create Zone operation: <items> XML template for the Create Zone operation
<items> <item> <parameters> <zone-path</zone-path> </parameters> </item> </items>
The following table describes the elements for the adapter request: Adapter request elements for the Create Zone operation Element <operation-type> <operation-name> <zone-name> <zone-path> Definition Defines the type of operation: Configure_Zone Defines the name of operation: Create_Zone Specifies the name of the Zone that you want to create Required Yes Yes Yes
Specifies the absolute path in which the zone files are Yes installed You must have access permission for the specified Zone path. Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 No No
<host> <port>
No
No
<password>
694
Note If the specified zone path exists before you create the Zone, the access modifiers must be only for the superuser.
The following figure shows the sample adapter request for the Create Zone operation: Sample adapter request for the Create Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Create_Zone</operation-name> <operation-timeout-secs>400</operation-timeout-secs> <zone-name>testzone1</zone-name> <parameters> <zone-path>/export/test/zones</zone-path> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Create Zone operation
695
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z testzone1 "create;set zonepath=/export/test/zones/"</command> <line-count>1</line-count> <execution-milliseconds>62</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Create_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Create Zone With Custom Settings operation
The Create Zone With Custom Settings operation creates a new Zone with advanced configuration options. This operation enables you to add virtual devices, such as a hard disk or an ethernet card, to a newly created Zone. The following figure shows the <items> XML template for the Create Zone With Custom Settings operation: <items> XML template for the Create Zone With Custom Settings operation
<items> <item> <parameters> <zone-path></zone-path> <autoboot></autoboot> <pool></pool> <boot-arguments></boot-arguments> <dedicated-cpu> <no-of-cpu></no-of-cpu> <cpu-importance></cpu-importance> </dedicated-cpu> <privileges></privileges> <scheduling-class></scheduling-class> <capped-memory> <physical></physical> <swap></swap>
696
<locked></locked> </capped-memory> <file-systems> <file-system> <dir></dir> <special></special> <type></type> </file-system> </file-systems> <datasets> <dataset> <name></name> </dataset> </datasets> <inherit-packages> <inherit-pkg> <dir></dir> </inherit-pkg> </inherit-packages> <ip-type></ip-type> <network-interfaces> <network-interface> <address></address> <physical></physical> <default-router></default-router> </network-interface> </network-interfaces> <cpu-shares></cpu-shares> <devices> <device> <match></match> </device> </devices> <max-sem-ids></max-sem-ids> <attributes> <attribute> <name></name> <type></type> <value></value> </attribute> </attributes>
697
The following table describes the elements for the adapter request. Note You can use the Fair Share Scheduler (FSS) to control the allocation of available CPU resources among Zones, based on their importance. This importance is expressed by the number of shares of CPU resources that you assign to each Zone.
Adapter request elements for the Create Zone With Custom Settings operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Specifies the type of operation: Configure_Zone Specifies the operation: Create_Zone_With_Custom_Settings Specifies the name for the Zone that you want to create Specifies the name of the computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes No No
<operation-timeout-secs> Specifies the time, in seconds, to wait for the operation to finish on the target server If the operation is not successful within this interval, the adapter returns an error message. Default value: 300 seconds <zone-path> Specifies the path in which the Zone files are installed You must have access permission for the specified Zone path. <autoboot> Specifies whether the Zone is booted when the associated Global Zone is booted Valid values: true = Zone booted false = Zone not booted (default) <pool> Specifies the configured pool name for the new Zone to bind
No
Yes
No
No
698
<boot-arguments> <dedicated-cpu> <no-of-cpu>
Specifies persistent boot arguments for the Zone Specifies the number of dedicated CPUs for the Zone Sets the number of CPUs for the Zone
No No Conditional Required if you specify the <dedicated-cpu> element No No
<cpu-importance> <cpu-shares>
Sets the importance for the CPU Specifies the number of Fair Share Scheduler (FSS) shares to allocate to this Zone This property is incompatible with the <dedicated-cpu> element.
<privileges>
Specifies the privileges to revise the default set of privileges For example, to add the ability to set the system clock to the default set of privileges, you can use this element.
No
<scheduling-class>
Provides different CPU access characteristics to threads, based on algorithmic logic Valid values: Real-time scheduling class (RT) Interactive scheduling class (IA) Fixed-priority scheduling class (FX) Timesharing scheduling class (TS) Fair-share scheduling class (FSS)
No
<capped-memory>
Sets the memory capacity for the Zone; enables you to place a soft restriction on the amount of memory that the Zone can use For example, to set the memory capacity for the Zone to 500 MB, set this element to 500m.
No
<physical>
Sets the physical memory capacity for the Zone; enables you to restrict the amount of physical memory that the Zone can use For example, to set the physical memory of the Zone to 500 MB, set this element to 500m.
Conditional If you specify <capped-memory>, you must also specify <physical>, <swap>, or <locked>.
<swap>
Sets the swap memory capacity for the Zone; Conditional enables you to restrict the amount of virtual If you specify memory that the Zone can use <capped-memory>, you must also specify <physical>, For example, to set the virtual memory of the <swap>, or <locked>. Zone to 1 GB, set this element to 1g.
699
<locked>
Sets the locked memory capacity for the Zone; enables you to place a locked memory cap on the amount of physical memory that the Zone can use For example, to set the locked memory capacity of the Zone to 50 MB, set this element to 50m.
Conditional If you specify the <capped-memory> element, you must also specify <physical>, <swap>, or <locked>.
<file-systems> <file-system>
Contains file systems to add to the Zone Specifies a file system to add to the Zone
No Conditional Required if you specify <file-systems> Conditional Required if you specify <file-system> Conditional Required if you specify the <file-system> element Conditional Required if you specify <file-system> No Conditional Required if you specify <datasets> Conditional Required if you specify <datasets> No Conditional Required if you specify <inherit-packages> Conditional Required if you specify <inherit-pkg> No
<dir>
Sets the mount point for the file system
<special>
Sets the special file system for the Zone
<type>
Specifies the type of file system for <file-system> Contains Zettabyte File System (ZFS) datasets in the storage pool Specifies a ZFS dataset to add to the Zone
<datasets> <dataset>
<name>
Specifies path for the ZFS dataset
<inherit-packages> <inherit-pkg>
Contains file systems that are loopback mounted from the Global Zone Adds a shared file system that is loopback mounted from the Global Zone Specifies the directory on the Global Zone to mount in the read-only mode Sets the Internet protocol type for the Zone to Exclusive-IP Default value: Shared-IP Contains network interfaces Specifies a network interface to add to the Zone Sets the IP address for the network interface
<dir>
<ip-type>
<network-interfaces> <network-interface>
No Conditional Required if you specify <network-interfaces> Conditional Required if you specify <network-interfaces>
<address>
700
<physical>
Sets the physical device type for the network interface Sets the default router for the network interface Contains network devices Specifies a device to add to the Zone
Conditional Required if you specify <network-interfaces> No No Conditional Required if you specify <devices> Conditional Required if you specify <device> No No Conditional Required if you specify <attributes> Conditional Required if you specify <attribute> Conditional Required if you specify <attribute> Conditional Required if you specify <attributes> No
<default-router> <devices> <device>
<match>
Sets the device match
<max-sem-ids> <attributes> <attribute>
Sets the maximum number of semaphore IDs for the Zone Contains properties for the Zone Specifies an attribute to add for the Zone
<name>
Specifies the name for the attribute
<type>
Specifies the type of the attribute
<value>
Contains the value for the attribute
<user-name>
Specifies the user name for the Solaris computer If you specify no user name, the request is executed with the user name specified in the adapter configuration.
<password>
Specifies the password corresponding to the user name
Conditional Required if you specify <user-name>
The following figure shows a sample adapter request for the Create Zone With Custom Settings operation, using only the required elements: Sample adapter request for the Create Zone With Custom Settings operation using only the required elements
701
<solaris-zones-request> <operation-type>Configure_Zone</operation-type> <operation-name>Create_Zone_With_Custom_Settings</operation-name> <zone-name>Testzone</zone-name> <parameters> <zone-path>/export/home/zones</zone-path> </parameters> </solaris-zones-request>
The following figure shows a sample adapter request for the Create Zone With Custom Settings operation with the optional elements: Sample adapter request for the Create Zone With Custom Settings operation with the optional elements
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Create_Zone_With_Custom_Settings</operation-name> <zone-name>testzone</zone-name> <parameters> <zone-path>/zone/Demozone3</zone-path> <autoboot>true</autoboot> <pool></pool> <network-interfaces> <network-interface> <address>10.118.243.40</address> <physical>eri0</physical> </network-interface> </network-interfaces> <dedicated-cpu> <no-of-cpu>2</no-of-cpu> <cpu-importance>89</cpu-importance> </dedicated-cpu> <capped-memory> <physical>1M</physical> <swap>50M</swap> <locked>10</locked> </capped-memory> <scheduling-class>FSS</scheduling-class> <privileges></privileges> <file-systems> <file-system> <dir>/usr/local</dir> <special>/export/home/zones</special> <type>lofs</type> </file-system> </file-systems>
702
<datasets> <dataset> <name>/zones</name> </dataset> </datasets> <inherit-packages> <inherit-pkg> <dir>/export/home/zones</dir> </inherit-pkg> </inherit-packages> <ip-type>exclusive</ip-type> <devices> <device> <match></match> </device> </devices> <max-sem-ids>10485200</max-sem-ids> <attributes> <attribute> <name>comment</name> <type>string</type> <value>"This is my work zone."</value> </attribute> </attributes>
703
<operation-timeout-secs>700</operation-timeout-secs> </parameters> </solaris-zones-request>
The following figure shows the response for the sample Create Zone With Custom Settings operation: Sample adapter response for the Create Zone With Custom Settings operation
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="10.128.30.62"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>echo . | zonecfg -z "Testzone" "create ; set zonepath="/export/home/zones"; exit;"</command> <line-count>1</line-count> <execution-milliseconds>170</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Create_Zone_With_Custom_Settings executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Create Zone From Template operation
The Create Zone From Template operation enables you to create a Zone from an existing Zone configuration template. The following figure shows an <items> XML template for the Create Zone From Template operation: <items> XML template for the Create Zone From Template operation
704
<items> <item> <parameters> <template></template> </parameters> </item> </items>
The following table describes the elements for the adapter request: Adapter request elements for the Create Zone From Template operation Element <operation-type> <operation-name> <zone-name> <template> <host> <port> Definition Defines the type of operation: Configure_Zone Defines the name of operation: Create_Zone_ From_Template Specifies the name of the Zone that you want to create Specifies the Zone configuration template for the new Zone that you want to create Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes Yes No No
No
No
<password>
The following figure shows the sample adapter request for the Create Zone From Template operation: Sample adapter request for the Create Zone From Template operation
705
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Create_Zone_From_Template</operation-name> <zone-name>mygridzone1</zone-name> <parameters> <template>/zone/master</template> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Create Zone From Template operation
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "mygridzone1" -f "/zone/master"</command> <line-count>1</line-count> <execution-milliseconds>86</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Create_Zone_From_Template executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
706
Request and response for the Clone Zone operation

The Clone Zone operation is used to clone a Zone with the same configuration as the specified Zone. This operation creates a new Zone on the Solaris computer by copying the Zone information from the source Zone path to the target Zone path. Note You can perform the Clone Zone operation only for Zones in the installed or running state.
The following figure shows an <items> XML template for the Clone Zone operation: <items> XML template for the Clone Zone operation
<items> <item> <parameters> <new-zone-name></new-zone-name> <new-zone-path></new-zone-path> </parameters> </item> </items>
The following table describes the elements for the adapter request: Adapter request elements for the Clone Zone operation Element <operation-type> <operation-name> <zone-name> <new-zone-name> <new-zone-path> <host> <port> Definition Defines the type of operation: Configure_Zone Defines the name of operation: Clone_Zone Specifies the name of the source Zone that you want to clone from Specifies the name for the newly cloned Zone Specifies the zone path for the newly cloned Zone Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Required Yes Yes Yes Yes Yes No No
No
707
<user-name>
No
<password>
The following figure shows the sample adapter request for the Clone Zone operation: Sample adapter request for the Clone Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Clone_Zone</operation-name> <zone-name>newzone</zone-name> <parameters> <new-zone-name>Clonedzone1</new-zone-name> <new-zone-path>/export/zones/clonedzone</new-zone-path> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Clone Zone operation
708
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zoneadm -z "newzone" halt; zonecfg -z "newzone" export -f master1273057592734; zonecfg -z "clonedzone1" -f master1273057592734; zonecfg -z "clonedzone1" "set zonepath="/export/zones/clonedzone""; zoneadm -z "clonedzone1" clone newzone; rm -f master1273057592734</command> <line-count>6</line-count> <execution-milliseconds>1047</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Clone_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Retrieve Zone Configuration operation

The Retrieve Zone Configuration operation enables you to retrieve the configuration parameters for the specified Zone. The following table describes the elements for the adapter request: Adapter request elements for the Retrieve Zone Configuration operation Element <operation-type> <operation-name> <zone-name> Definition Defines the type of operation: Configure_Zone Defines the name of operation: Retrieve_Zone_Configuration Specifies the name of the Zone for which you want to retrieve the configuration parameters Required Yes Yes Yes No
709
<host> <port>
Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 Specifies the user name for the Solaris computer If no user name is specified, the request is executed with the user name specified in the adapter configuration. Specifies the password corresponding to the user name
No No
<user-name>
No
<password>
The following figure shows the sample adapter request for the Retrieve Zone Configuration operation: Sample adapter request for the Retrieve Zone Configuration operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Retrieve_Zone_Configuration</operation-name> <zone-name>zone1</zone-name> </solaris-zones-request>
The following figure shows the response for the sample adapter request: Sample adapter response for the Retrieve Zone Configuration operation
710
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "zone1" info</command> <line-count>20</line-count> <execution-milliseconds>731</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">zonename: zone1</line> <line index="2">zonepath: /zones/testzone1</line> <line index="3">brand: native</line> <line index="4">autoboot: true</line> <line index="5">bootargs: </line> <line index="6">pool: </line> <line index="7">limitpriv: </line> <line index="8">scheduling-class: </line> <line index="9">ip-type: shared</line> <line index="10">inherit-pkg-dir:</line> <line index="11"> dir: /lib</line> <line index="12">inherit-pkg-dir:</line> <line index="13"> dir: /platform</line> <line index="14">inherit-pkg-dir:</line> <line index="15"> dir: /sbin</line> <line index="16">inherit-pkg-dir:</line> <line index="17"> dir: /usr</line> <line index="18">net:</line> <line index="19"> address: 10.128.248.3</line> <line index="20"> physical: vnet0</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Update Zone Configuration operation

The Update Zone Configuration operation enables you to modify configuration parameters for a Zone. You can use this operation to add, update, or remove a hard disk, a CD-ROM, or an ethernet adapter from a Zone. The following figure shows the <items> XML template for the Update Zone Configuration operation: <items> XML template for the Update Zone Configuration operation
711
<items> <item> <parameters> <remove-resources> <autoboot/> <cpu-shares></cpu-shares> <pool/> <boot-arguments/> <dedicated-cpu> <no-of-cpu></no-of-cpu> </dedicated-cpu> <privileges/> <scheduling-class/> <capped-memory> <physical></physical> </capped-memory> <file-systems> <file-system> <dir></dir> </file-system> </file-systems> <datasets> <dataset> <name></name> </dataset> </datasets> <inherit-packages> <inherit-pkg> <dir></dir> </inherit-pkg> </inherit-packages> <ip-type/> <network-interfaces> <network-interface> <address></address> </network-interface> </network-interfaces> <devices> <device> <match></match> </device> </devices> <ma-sem-ids/> <attributes> <attribute> <name></name> </attribute> </attributes> </remove-resources> <add-resources> <autoboot></autoboot> <cpu-shares></cpu-shares> <pool></pool> <boot-arguments ></boot-arguments>
712
<dedicated-cpu> <no-of-cpu></no-of-cpu> <cpu-importance></cpu-importance> </dedicated-cpu> <privileges></privileges> <scheduling-class></scheduling-class> <capped-memory> <physical></physical> <swap></swap> <locked></locked> </capped-memory> <file-systems> <file-system> <dir></dir> <special></special> <type></type> </file-system> </file-systems> <datasets> <dataset> <name></name> </dataset> </datasets> <inherit-packages> <inherit-pkg> <dir></dir> </inherit-pkg> </inherit-packages> <ip-type></ip-type> <network-interfaces> <network-interface> <address></address> <physical></physical> <default-router></default-router> </network-interface> </network-interfaces> <devices> <device> <match></match> </device> </devices> <ma-sem-ids></ma-sem-ids> <attributes> <attribute> <name></name> <type></type> <value></value> </attribute> </attributes> </add-resources> <update-resources> <zone-path></zone-path> <autoboot></autoboot> <cpu-shares></cpu-shares> <pool></pool> <boot-arguments ></boot-arguments>
713
<dedicated-cpu> <no-of-cpu></no-of-cpu> <cpu-importance></cpu-importance> </dedicated-cpu> <privileges></privileges> <scheduling-class></scheduling-class> <capped-memory> <physical></physical> <swap></swap> <locked></locked> </capped-memory> <file-systems> <file-system> <dir></dir> <special></special> <type></type> </file-system> </file-systems> <datasets> <dataset name> <name></name> </dataset> </datasets> <inherit-packages> <inherit-pkg> <dir></dir> </inherit-pkg> </inherit- packages> <ip-type></ip-type> <network-interfaces> <network-interface> <address></address> <physical></physical> <default-router></default-router> </network-interface> </network-interfaces> <devices> <device match> <match></match> </device> </devices> <max-sem-ids></max-sem-ids> <attributes> <attribute name> <name></name> <type></type> <value></value> </attribute> </attributes> </update-resources>
714
</parameters> <item> </items>
The following table describes the elements for the adapter request: Adapter request elements for the Update Zone Configuration operation Element <operation-type> <operation-name> <zone-name> <host> <port> Definition Specifies the type of operation: Configure_Zone Specifies the operation: Update_Zone_Configuration Specifies the name of the Zone whose configuration parameters you want to update Required Yes Yes Yes
Specifies the name of the Solaris computer hosting No Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22 No
<operation-timeout-secs> Specifies the time, in seconds, to wait for the operation to finish on the target server If the operation is not successful within this interval, the adapter returns an error message. Default value: 300 seconds <user-name> Specifies the user name for the Solaris computer If you specify no user name, the request is executed with the user name specified in the adapter configuration. <password> Specifies the password corresponding to the user name
No
No
Conditional Required if you specify <user-name>
715
<add-resources>
Contains resources to add to the Zone configuration Note Global parameters cannot have multiple entries with a zone. Therefore, when you use the <add-resource> element, if a resource is already present within a zone, the value of the resource is updated; otherwise, its value is added to the configuration.
No
For information about the child elements, see Child elements for the <add-resources>, <remove-resources>, and <update-resources> elements. <autoboot> Specifies whether the Zone is booted when the associated Global Zone is booted Valid values: true = Zone booted false = Zone not booted (default) <cpu-shares> Specifies the number of Fair Share Scheduler (FSS) shares to update in the specified Zone This property is incompatible with the <dedicated-cpu> element. <pool> <boot-arguments> <dedicated-cpu> <no-of-cpu> Specifies the configured pool name for the new Zone to bind Specifies persistent boot arguments for the Zone Specifies the number of dedicated CPUs for the Zone Sets the number of CPUs for the Zone No No No Conditional Required if you specify the <dedicated-cpu> element No No No No
<cpu-importance> <privileges>
Sets the importance for the CPU Specifies the privileges to revise the default set of privileges For example, to add the ability to set the system clock to the default set of privileges, you can use this element.
716
<scheduling-class>
Provides different CPU access characteristics to threads, based on algorithmic logic Valid values: Real-time scheduling class (RT) Interactive scheduling class (IA) Fixed-priority scheduling class (FX) Timesharing scheduling class (TS) Fair-share scheduling class (FSS)
No
<capped-memory>
Sets the memory capacity for the Zone; enables you to place a soft restriction on the amount of memory that the Zone can use For example, to set the memory capacity for the Zone to 500 MB, set this element to 500m.
No
<physical>
Sets the physical memory capacity for the Zone; enables you to restrict the amount of physical memory that the Zone can use For example, to set the physical memory of the Zone to 500 MB, set this element to 500m.
Conditional If you specify <capped-memory>, you must also specify <physical>, <swap>, or <locked>. Conditional If you specify <capped-memory>, you must also specify <physical>, <swap>, or <locked>. Conditional If you specify the <capped-memory> element, you must also specify <physical>, <swap>, or <locked>. No Conditional Required if you specify <file-systems> Conditional Required if you specify <file-system> Conditional Required if you specify the <file-system> element Conditional Required if you specify <file-system> No
<swap>
Sets the swap memory capacity for the Zone; enables you to restrict the amount of virtual memory that the Zone can use For example, to set the virtual memory of the Zone to 1 GB, set this element to 1g.
<locked>
Sets the locked memory capacity for the Zone; enables you to place a locked memory cap on the amount of physical memory that the Zone can use For example, to set the locked memory capacity of the Zone to 50 MB, set this element to 50m.
<file-systems> <file-system>
Contains file systems to add to the Zone Specifies a file system to add to the Zone
<dir>
Sets the mount point for the file system
<special>
Sets the special file system for the Zone
<type>
Specifies the type of file system for <file-system> Contains Zettabyte File System (ZFS) datasets in the storage pool
<datasets>
717
<dataset>
Specifies a ZFS dataset to add to the Zone
Conditional Required if you specify <datasets> Conditional Required if you specify <datasets> No Conditional Required if you specify <inherit-packages> Conditional Required if you specify <inherit-pkg> No
<name>
Specifies path for the ZFS dataset
<inherit-packages> <inherit-pkg>
Contains file systems that are loopback mounted from the Global Zone Adds a shared file system that is loopback mounted from the Global Zone Specifies the directory on the Global Zone to mount in the read-only mode Sets the Internet protocol type for the Zone to Exclusive-IP Default value: Shared-IP Contains network interfaces Specifies a network interface to add to the Zone
<dir>
<ip-type>
<network-interfaces> <network-interface>
No Conditional Required if you specify <network-interfaces> Conditional Required if you specify <network-interfaces> Conditional Required if you specify <network-interfaces> No No Conditional Required if you specify <devices> Conditional Required if you specify <device> No No Conditional Required if you specify <attributes> Conditional Required if you specify <attribute>
<address>
Sets the IP address for the network interface
<physical>
Sets the physical device type for the network interface Sets the default router for the network interface Contains network devices Specifies a device to add to the Zone
<default-router> <devices> <device>
<match>
Sets the device match
<max-sem-ids> <attributes> <attribute>
Sets the maximum number of semaphore IDs for the Zone Contains properties for the Zone Specifies an attribute to add for the Zone
<name>
Specifies the name for the attribute
718
<type>
Specifies the type of the attribute
Conditional Required if you specify <attribute> Conditional Required if you specify <attributes>
<value>
Contains the value for the attribute
<remove-resources>
Contains resources to remove from the Zone No configuration For information about the child elements, see Child elements for the <add-resources>, <remove-resources>, and <update-resources> elements. Contains one or more resources to update in the No Zone configuration For information about the child elements, see Child elements for the <add-resources>, <remove-resources>, and <update-resources> elements.
<update-resources>
The following table describes the child elements of the <add-resources>, <remove-resources>, and <update-resources> elements: Child elements for the <add-resources>, <remove-resources>, and <update-resources> elements Element Definition Required Conditional Required if you specify <add-resources> Conditional Required if you specify <add-resources> Conditional Required if you specify <add-resources>
<resource> Specifies the resource to add, remove, or update from the Zone configuration <name> Specifies the name of the resource to add, remove, or update
<value>
Specifies the value for the resource
The following figure shows a sample adapter request for the Update Zone Configuration operation for adding, updating, and deleting virtual devices: Sample adapter request for the Update Zone Configuration operation for adding, updating, and deleting virtual devices
719
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Update_Zone_Configuration</operation-name> <zone-name>testzone</zone-name> <parameters> <add-resources> <autoboot>false</autoboot> <cpu-shares>80</cpu-shares> </add-resources> <update-resources> <cpu-shares>60</cpu-shares> </update-resources> <remove-resources> <cpu-shares>60</cpu-shares> </remove-resources> </parameters> </solaris-zones-request>
Note You must specify the elements in the <target> block of the adapter request only if you want to override the elements specified in the adapter configuration.
The following figure shows the response for the sample adapter request: Sample adapter response for the Update Zone Configuration operation for adding, updating, and deleting virtual devices
720
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="10.118.14.6"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "zone1" "set autoboot=false; add dedicated-cpu;set ncpus=1; set importance=8; end; add capped-memory;set physical=1M; set swap=51M; set locked=9; end; set bootargs=\"-m verbose1\"; select net address=10.118.218.3; set address=10.118.218.2; set physical=vnet0; end; "</command> <line-count>1</line-count> <execution-milliseconds>797</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Update_Zone_Configuration executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
The following figure shows a sample adapter request for adding a virtual device: Sample adapter request for adding a virtual device
<solaris-zones-request> <operation-type>Configure_Zone</operation-type> <operation-name>Update_Zone_Configuration</operation-name> <operation-timeout-secs>300</operation-timeout-secs> <zone-name>testingzoneOneTwo</zone-name> <parameters> <add-resources> <autoboot>false</autoboot> <cpu-shares>80</cpu-shares> </add-resources> <update-resources /> <remove-resources /> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request for adding a virtual device: Sample adapter response for the Update Zone Configuration operation for adding a virtual device
721
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "testingzoneOneTwo" "set autoboot=false; set cpu-shares=80; "</command> <line-count>1</line-count> <execution-milliseconds>1031</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Update_Zone_Configuration executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
The following figure shows a sample adapter request for updating a virtual device: Sample adapter request for updating a virtual device
<solaris-zones-request> <operation-type>Configure_Zone</operation-type> <operation-name>Update_Zone_Configuration</operation-name> <operation-timeout-secs>300</operation-timeout-secs> <zone-name>testingzoneOneTwo</zone-name> <parameters> <add-resources> <autoboot>false</autoboot> </add-resources> <update-resources> <cpu-shares>60</cpu-shares> </update-resources> <remove-resources /> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request for updating a virtual device: Sample adapter response for the Update Zone Configuration operation for updating a virtual device
722
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "testingzoneOneTwo" "set autoboot=false; set cpu-shares=60; "</command> <line-count>1</line-count> <execution-milliseconds>703</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Update_Zone_Configuration executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
The following figure shows a sample adapter request for deleting a virtual device: Sample adapter request for deleting a virtual device
<solaris-zones-request> <solaris-zones-request> <operation-type>Configure_Zone</operation-type> <operation-name>Update_Zone_Configuration</operation-name> <operation-timeout-secs>300</operation-timeout-secs> <zone-name>testingzoneOneTwo</zone-name> <parameters> <add-resources> <autoboot>false</autoboot> </add-resources> <update-resources /> <remove-resources> <cpu-shares>60</cpu-shares> </remove-resources> </parameters> </solaris-zones-request>
The following figure shows the response for the sample adapter request for deleting a virtual device: Sample adapter response for the Update Zone Configuration operation for deleting a virtual device
723
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "testingzoneOneTwo" "clear cpu-shares; set autoboot=false; "</command> <line-count>1</line-count> <execution-milliseconds>844</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Update_Zone_Configuration executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
Request and response for the Delete Zone operation

The Delete Zone operation enables you to delete a Zone only if it is in the configured state. The following figure shows an <items> XML template for the Delete Zone operation: <items> XML template for the Delete Zone operation
<items> <item> <parameters> <zone-path</zone-path> </parameters> </item> </items>
The following table describes the elements for the adapter request: Adapter request elements for the Delete Zone operation Element <operation-type> Definition Defines the type of operation: Configure_Zone Required Yes
724
<operation-name> <zone-name> <zone-path> <host> <port>
Defines the name of operation: Delete_Zone Specifies the name of the Zone that you want to delete Specifies the zone path for the Zone that you want to delete Specifies the host name of the Solaris computer hosting Solaris Zones Specifies the port on which the SSH service is running on the host computer Default value: 22
Yes Yes No No No
No
No
<password>
The following figure shows the sample adapter request for the Delete Zone operation: Sample adapter request for the Delete Zone operation
<solaris-zones-request> <target> <host>vm-sol-abc<host> <user-name>admin<user-name> <password>adminpass</password> <port>8888</port> </target> <operation-type>Configure_Zone</operation-type> <operation-name>Delete_Zone</operation-name> <operation-timeout-secs>200</operation-timeout-secs> <zone-name>testzone</zone-name> <parameters> <zone-path>/export/zones/testzone</zonepath> <parameters> </solaris-zones-request>
725
The following figure shows the response for the sample adapter request: Sample adapter response for the Delete Zone operation
<solaris-zones-response> <metadata> <status>success</status> </metadata> <target-output host="vm-sol-abc"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <operation-output> <metadata> <command>zonecfg -z "testzone" delete -F; rm -rf "/export/zones/testzone"</command> <line-count>1</line-count> <execution-milliseconds>16078</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Operation Delete_Zone executed successfully!!</line> </output> </operation-output> </target-output> </solaris-zones-response>
BMC Atrium Orchestrator Application Adapter for VMware Infrastructure

The application adapter enables BMC Atrium Orchestrator workflow processes to perform specialized functions and to interact with VMware Infrastructure by providing an interface between the workflow processes and VMware Infrastructure. BMC Atrium Orchestrator application adapter for VMware Infrastructure consists of an actor, an event monitor and an SNMP monitor adapter and workflow processes.
Actor adapter
The actor adapter executes operations on VMware Infrastructure by using the VMware SDK API. To execute the operations, the adapter invokes Web Service calls on the VMware SDK API. The actor adapter can perform the following categories of operations: Basic VM operations Basic VApp operations Advanced VM operations Configure VM operations
726
Monitor VM operations Host operations Cluster operations Datacenter operations Datastore operations Discovery operations Folder operations Resource Pool operations Configure VApp operations
Monitor adapter
The event monitor adapter uses the VMware SDK API to listen for events, including Vmotion events, that are generated on VMware Infrastructure. The SNMP monitor adapter listens to the SNMP traps sent by VMware Virtual Center.
Note VMware Virtual Center must be configured to send SNMP traps to the BMC Atrium Orchestrator peer on which the adapter is enabled.
An event is evaluated by rules and can trigger specific workflow processes when the rule criteria are met.
Getting started with the BMC Atrium Orchestrator Application Adapter for VMware Infrastructure
This chapter describes the life cycle of the adapter module, prerequisites, and provides information about configuring the adapter.
Supported versions of VMware Infrastructure

The adapter supports:
VMware vSphere version 4.1 VMware vSphere version 4.0 VMware Infrastructure version 3.x Note The 20.11.01 version of the adapter is certified with ESX hosts versions 3.0, 3.5, 4.0, and 4.1 and VMware Virtual Center versions 2.5, 4.0, and 4.1.
Prerequisites for the BMC Atrium Orchestrator application adapter for VMware Infrastructure
The prerequisites for the actor and monitor adapters are:
727
The JAVA_HOME environment variable must point to the folder where JVM is installed. The PATH environment variable must contain the entry for JAVA_HOME/bin. For the VMware Infrastructure adapter to function properly, you must add an SSL certificate to the keystore of the BMC Atrium Orchestrator peer on which the adapter is enabled. See Adding an SSL certificate to the peer keystore. The SSL certificate is not needed if the communication between the peer and the VMware Infrastructure adapter does not use SSL.
Configuring the BMC Atrium Orchestrator application adapter for VMware Infrastructure
You configure an adapter in Grid Manager. The configuration provides information about how the adapter interacts with the VMware Infrastructure application. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties Note Before creating an adapter configuration, ensure that you have completed all the pre-requisite tasks.
Configuring the VMware Infrastructure actor adapter

To configure the actor adapter: 1. Log on to BMC Atrium Orchestrator Grid Manager. 2. To access the adapters page, click the Manage tab, and click the Adapters tab. 3. On the Adapters in Repository page, select the check box corresponding to The page Conrefs does not exist. . 4. Click Add to Grid. The adapter is now listed under Adapters on Grid. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to Step 7 to configure the adapter using the XML view: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Under Properties, enter or select values for the configuration elements. Include all required elements indicated with an asterisk (*). 7. (optional) Configure the adapter in the XML view using the following substeps: a. Specify a name for the adapter. Note The default adapter name is VMwareInfrastructure.
b. c. d. e. f.
Specify a description for the adapter. Click Switch to XML View. Click OK. On the Warning message that appears, click Switch View. In Properties, type the adapter configuration properties in an XML format, including all required elements. The Properties text box must contain a valid XML configuration node for the adapter, as shown in the following code sample. This sample shows all possible elements. If the default value for a non-required element is acceptable, omit the element. Do not include empty elements. XML sample for configuring the actor adapter
728
<config> <soap-url>https://dev1:443/sdk/vim</soap-url> <transport>https-rpc</transport> <user-name>administrator</user-name> <password>xyz345</password> <return-mob-ref>false</return-mob-ref> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> <allow-unsigned-certificate>true</allow-unsigned-certificate> </config>
g. Click OK. h. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list.
The following table describes the adapter configuration elements and attributes for the adapter that you can specify using the form view, XML view, or both. Note Switching to the XML view to specify configuration elements means that you cannot thereafter use the form for modifying the adapter configuration.
Node elements required to configure the actor adapter UI Label Soap URL Element <soap-url> Description Required?
The URL for the remote SOAP service Yes running on the VMware Virtual Center Default value format for HTTPS: https://hostname:port/sdk/vim Default value format for HTTP: http://hostname:port/sdk/vim If the remote SOAP service running on the VMware Virtual Center installed on default ports: Default value format for HTTPS: https://hostname/sdk/vim Default value format for HTTP: http:// hostname /sdk/vim" Note: If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
729
Transport
<transport>
Transport protocol for the message Default value: https-rpc Valid values: https-rpc, http-rpc If the value of the <transport> tag is https-rpc, install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. The user name that will be used for HTTP basic authentication on the VMware Virtual Center The password corresponding to the specified user name Specifies the format of adapter response. The valid values for this element are True and False. If the value is true, all adapter responses contain Managed Object IDs. If the value is false, all adapter responses contain display names. The default value for this element is false. Specifies whether to use a SSL certificate The valid values for this element are True and False. For installing certificates automatically, this element must be set to True. Specifies whether to install certificates automatically The valid values for this element are True and False.For installing VMware certificates automatically, this element must be set to True. Specifies the passphrase associated with the certificate The default value of this element is changeit.
Yes
User Name
<user-name>
Yes
Password
<password>
Yes No
Return Mob <return-mob-ref> Ref
Use SSL Certificate
Conditional; set <use-sslcertificate> to true if <soap-url> specifies a secure URL (https) No
Install Certificate
No
Allow Unsigned Certificate
<allow-unsigned-certificate> Specifies whether to install unsigned certificates automatically The valid values for this element are True and False. The default value is False.
No
Note You can configure the adapter to install certificates automatically by using the <use-ssl-certificate>, <install-certificate> and the <allow-unsigned-certificate> elements. The adapter can install certificates automatically only in the secure communication mode.
Configuring the VMware Infrastructure event monitor adapter
730
To configure the event monitor adapter: 1. Log on to BMC Atrium Orchestrator Grid Manager. 2. To access the adapters page, click the Manage tab, and click the Adapters tab. 3. On the Adapters in Repository page, select the check box corresponding to bmc-adapter-vmware-infrastructure-event-monitor. 4. Click Add to Grid. The adapter is now listed under Adapters on Grid. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to Step 7 to configure the adapter using the XML view: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Under Properties, enter or select values for the configuration elements. The configuration elements for the adapter are described in [Node elements required to configure the event monitor adapter ]. Include all required elements indicated with an asterisk (*). d. (optional) Click Switch to XML View and use the following steps to specify elements that are not in the form view. i. On the Warning message that appears, click Switch View. ii. In the Properties text box, use XML format to enter the <targets> configuration element, which is not available in the form view. 7. (optional) Configure the adapter in the XML view using the following substeps: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Click Switch to XML View. d. Click OK. e. On the Warning message that appears, click Switch View. f. In Properties, type the adapter configuration properties in an XML format, including all required elements. g. Click OK. h. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list.
The Properties text box must contain a valid XML configuration node for the adapter, as shown in the following code samples. XML sample for configuring the event monitor adapter
731
<config> <targets> <target> <soap-url>https://rba-dev910:443/sdk/vim</soap-url> <transport>https-rpc</transport> <user-name>rba</user-name> <password>rba</password> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> <allow-unsigned-certificate>true</allow-unsigned-certificate> </target> <target> <soap-url>https://rba-dev9:443/sdk/vim</soap-url> <transport>https-rpc</transport> <user-name>rba</user-name> <password>rba</password> </target> </targets> <return-history>false</return-history> <event-types> <event-type>VmPoweredOnEvent</event-type> </event-types> </config>
Warning Do not include empty elements in an adapter configuration as such elements may cause errors. If you want the event monitor adapter to listen to multiple VMware VirtualCenter instances, use the <targets> element in the adapter configuration.
The following code sample illustrates an adapter configuration without the <targets> element. XML sample for configuring the event monitor adapter without the targets element
<config> <soap-url>https://rba-dev910:443/sdk/vim</soap-url> <transport>https-rpc</transport> <user-name>rba</user-name> <password>rba</password> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <passphrase>changeit</passphrase> <allow-unsigned-certificate>true</allow-unsigned-certificate> <return-history>false</return-history> <event-types> <event-type>VmPoweredOnEvent</event-type> </event-types> </config>
732
The following table describes the adapter configuration elements and attributes for the adapter that you can specify using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the UI label column. Note Switching to the XML view to specify configuration elements means that you cannot thereafter use the form for modifying the adapter configuration.
Node elements required to configure the event monitor adapter UI Label Element <targets> Soap Url <soap-url> Description Contains the details for multiple VMware VirtualCenter instances The URL for the remote SOAP service running on the VMware Virtual Center Default value format for HTTPS: https:// hostname:port/sdk/vim Default value format for HTTP:http:// hostname:port/sdk/vim Note: If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. Required? No Yes
Transport
<transport >
Transport protocol for the message Yes Default value: https-rpc Valid values: https-rpc, http-rpc If the value of the <transport> tag is https-rpc, install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. Specifies whether to use a SSL certificate No The valid values for this element are True and False. For installing certificates automatically, this element must be set to True. Specifies whether to install certificates automatically The valid values for this element are True and False.For installing VMware certificates automatically, this element must be set to True. Specifies the passphrase associated with the certificate The default value of this element is changeit. No
Use Ssl Certificate
Install Certifcate
Passphrase <passphrase> Allow Unsigned Certificate User Name Password
No No
<allow-unsigned-certificate> Specifies whether to install unsigned certificates automatically The valid values for this element are True and False. The default value is False. <user-name> <password> the user name used for HTTP basic authentication for the VMware Virtual Center The password corresponding to the specified user-name
Yes Yes
733
Return History
<return-history>
Indicates whether the past history of events of the type No specified in the adapter configuration is returned, when the adapter is enabled for the first time. Valid values: True, False. If the value is True, the previous history is returned in the first response as a collection of events. This element contains a list of <event-type> tags. Yes Each <event-type> tag specifies a type of event that needs to be captured. An <event-type> element with no child <event-type> tags is invalid. If you want to capture two or more event types, they must be specified in two or more different <event-type> tags in the same parent <event-types> tag. If you want to capture all event types, use 'ALL' for the <event-type>. If you specify any other event type along with the ALL event type, the ALL event type is ignored. Some examples of event types are: VmPoweredOffEvent VmPoweredOnEvent VmMigratedEvent VmEmigratingEvent VmBeingHotMigratedEvent
Event Types
<event-types>
Note You can configure the adapter to install certificates automatically by using the <use-ssl-certificate>, <install-certificate>, and the <allow-unsigned-certificate> elements. The adapter can install certificates automatically only in the secure communication mode.
Configuring the VMware Infrastructure SNMP monitor adapter

To configure the SNMP monitor adapter: 1. Log on to BMC Atrium Orchestrator Grid Manager. 2. To access the adapters page, click the Manage tab, and click the Adapters tab. 3. On the Adapters in Repository page, select the check box corresponding to bmc-adapter-vmware-infrastructure-snmp-monitor. 4. Click Add to Grid. The adapter is now listed under Adapters on Grid. 5. Click Configure corresponding to the newly added adapter. 6. On the Add an Adapter Configuration page, perform the following substeps to configure the adapter using the form view or jump to [Step 7] to configure the adapter using the XML view: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Under Properties, enter or select values for the configuration elements. The configuration elements for the adapter are described in . Include all required elements indicated with an asterisk (*). d. Click OK. 7. (optional) Configure the adapter in the XML view using the following substeps: a. Specify a name for the adapter. b. Specify a description for the adapter. c. Click Switch to XML View. d. Click OK. e. On the Warning message that appears, click Switch View. f.
734
f. In Properties, enter the adapter configuration properties in an XML format, including all required elements as indicated in [Configuration node elements:SNMP monitor adapter]. The Properties text box must contain a valid XML configuration node for the adapter, as shown in the following code sample. XML Sample for configuring the SNMP monitor adapter
<config> <port>1894</port> <version>2c</version> <mibs-directory>home/mydir/mibs</mibs-directory> </config>
Note To ensure that processes using the monitor adapter execute properly, the MIBS directory path specified in the SNMP monitor adapter configuration must exist on all peers, on which the monitor adapters are enabled. An invalid path can cause the adapter to go into the fault state.
Warning If the SNMP monitor adapter is configured with a port number less than 1024, you must ensure that the peer on which the adapter is enabled is configured with administrator or root privileges. This is a prerequisite for all operating systems except Microsoft Windows.
g. On the Warning message that appears, click Save. This saves the adapter configuration with settings in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list.
The following table describes the adapter configuration elements and attributes for the adapter that you can specify using the form view, XML view, or both. Note Switching to the XML view to specify configuration elements means that you cannot thereafter use the form for modifying the adapter configuration.
Configuration node elements: SNMP monitor adapter UI Label Port Version Element <port> <version> Description The port on which to listen for SNMP traps The SNMP version Required Yes Yes No
<mibs-directory> The directory location for SNMP MIBS Mibs The VMware Infrastructure MIBS files can be found in the Directory $VMware_install_directory\VirtualCenter Server\MIBS folder, where VMware_install_directory is the root installation directory for VMware Virtual Center.
735
Note You should avoid using an empty non-required element in the adapter configuration because it may cause errors.
BMC Atrium Orchestrator Application Adapter for VMware Infrastructure module

Each operation supported by the application adapter has a corresponding process in the Module. Top-level processes perform high-level functions and call operations in sub-directories. Each sub-directory contains process directories corresponding to the supported operation types.
Top-level processes for the VMware Infrastructure adapter

The top-level processes in the Project Explorer window execute the following version-specific VMware Infrastructure processes: Create Items Delete Items Find Items Perform Operations Update Items The top-level processes perform higher level functions and calls specialized processes in the sub directories.
SetupValidation directory for the VMware Infrastructure adapter

The processes in the SetupValidation directory contain sample values for the request elements. These sample values can be quickly changed to reflect the values in your environment. A process is provided to test each supported method of executing operations in VMware Infrastructure.
Utilities directory for the VMware Infrastructure adapter

The Utilities directory contains constructor processes that create the XML inputs used in version-specific processes. The constructor processes are organized into general utilities and sub-directories that correspond to the supported operation types. The functional processes require complex XML inputs. You can generate these complex XML inputs using the constructor processes. Example For the Power On VM operation, you can use the complex XML generated by the Construct Item for Power On VM constructor process.
The following table provides information about the available constructor processes: Constructor processes Constructor wrapper Name Description
736
Basic VM operations Construct Item for Power On VM Construct Item for Power Off VM Construct Item for Reset VM Construct Item for Suspend VM Construct Item for Resume VM Construct Item for Shut Down Guest OS Construct Item for Restart Guest OS Basic vApp operations Construct Item for Power On VApp Construct Item for Power Off VApp Construct Item for Unregister VApp Advanced VM Operations Construct Item for Create VM Snapshot Construct Item for Revert VM Snapshot Construct Item for Validate VM Migration Construct Item for Migrate VM Construct Item for Move Virtual Disk Construct Item for Relocate VM Construct Item for Acquire Mks Ticket Construct Item for Retrieve VM File Info Construct Item for Update VM Snapshot Construct Item for Delete VM Snapshot Configure VM Operations Construct Item for Create VM Construct Item for Create VM with Custom Settings Construct Item for Clone VM Construct Item for Clone VM with Custom Settings Construct Item for Add Hard Disk Construct Item for Delete VM Construct Item for Export VM as OVF Template Construct Item for Import OVF Template as VM Constructs Items XML for the Create VM wrapper Constructs Items XML for the Create VM with Custom Settings wrapper Constructs Items XML for the Clone VM wrapper Constructs Items XML for the Clone VM with Custom Settings wrapper Constructs Items XML for the Add Hard Disk wrapper Constructs Items XML for the Delete VM wrapper Constructs Items XML for the Export VM as OVF Template wrapper Constructs Items XML for the Import OVF Template as VM wrapper Constructs Items XML for the Create VM Snapshot wrapper Constructs Items XML for the Revert VM Snapshot wrapper Constructs Items XML for the Validate VM Migration wrapper Constructs Items XML for the Migrate VM wrapper Constructs Items XML for the Move Virtual Disk wrapper Constructs Items XML for the Relocate VM wrapper Constructs Items XML for the Acquire Mks Ticket wrapper Constructs Items XML for the Retrieve VM File Info wrapper Constructs Items XML for the Update VM Snapshot wrapper Constructs Items XML for the Delete VM Snapshot wrapper Constructs Items XML for the Power On VApp wrapper Constructs Items XML for the Power Off VApp wrapper Constructs Items XML for the Unregister VApp wrapper Constructs Items XML for the Power On VM wrapper Constructs Items XML for the Power Off VM wrapper Constructs Items XML for the Reset VM wrapper Constructs Items XML for the Suspend VM wrapper Constructs Items XML for the Resume VM wrapper Constructs Items XML for the Shut Down Guest OS wrapper Constructs Items XML for the Restart Guest OS wrapper
737
Construct Item for Retrieve VM Configuration Construct Item for Update VM Configuration Construct Item for Remove Ethernet Adapter Construct Item for Remove Hard Disk Construct Item for Remove CD ROM Construct Item for Add Ethernet Adapter Construct Item for Add CD ROM Construct Item for Retrieve CPU Configuration Construct Item for Retrieve Memory Configuration Construct Item for Retrieve Hard Disk Configuration Construct Item for Retrieve Ethernet Adapter Configuration Construct Item for Retrieve CD ROM Configuration Construct Item for Update CD ROM Configuration
Constructs Items XML for the Retrieve VM Configuration wrapper Constructs Items XML for the Update VM Configuration wrapper Constructs Items XML for the Remove Ethernet Adapter wrapper Constructs Items XML for the Remove Hard Disk wrapper Constructs Items XML for the Remove CD ROM wrapper Constructs Items XML for the Add Ethernet Adapter wrapper Constructs Items XML for the Add CD ROM wrapper Constructs Items XML for the Retrieve CPU Configuration wrapper Constructs Items XML for the Retrieve Memory Configuration wrapper Constructs Items XML for the Retrieve Hard Disk Configuration wrapper Constructs Items XML for the Retrieve Ethernet Adapter Configuration wrapper Constructs Items XML the Retrieve CD ROM Configuration wrapper Constructs Items XML for the Update CD ROM Configuration wrapper
Construct Item for Update CPU Configuration |Constructs Items XML for the Update CPU Configuration wrapper | Construct Item for Update Memory Configuration Construct Item for Update Ethernet Adapter Configuration Construct Item for Update Hard Disk Configuration Monitor VM operations Construct Item for Retrieve VM CPU Usage Construct Item for Retrieve VM Disk Usage Construct Item for Retrieve VM Memory Usage Construct Item for Retrieve VM Network Usage Construct Item for Retrieve VM Status Construct Item for Retrieve Task Status Construct Item for Retrieve VM Alarm List Construct Item for Delete VM Alarm Constructs Items XML for the Retrieve VM CPU Usage wrapper Constructs Items XML for the Retrieve VM Disk Usage wrapper Constructs Items XML for the Retrieve VM Memory Usage wrapper Constructs Items XML for the Retrieve VM Network Usage wrapper Constructs Items XML for the Retrieve VM Status wrapper Constructs Items XML for the Retrieve Task Status wrapper Constructs Items XML for the Retrieve VM Alarm List wrapper Constructs Items XML for the Delete VM Alarm wrapper Constructs Items XML for the Update Memory Configuration wrapper Constructs Items XML for the Update Ethernet Adapter Configuration wrapper Constructs Items XML for the Update Hard Disk Configuration wrapper
738
Host Operations Construct Item for Create Host Construct Item for Move Host to Cluster Construct Item for Add Host to Cluster Construct Item for Remove Host from Cluster Construct Item for Update Host Network Configuration Construct Item for Retrieve Host Configuration Construct Item for Retrieve Host DVS Configuration Construct Item for Retrieve Host Network Configuration Construct Item for Retrieve Host Datastore Configuration Construct Item for Retrieve Virtual Switch Configuration Construct Item for Retrieve Virtual NIC Configuration Construct Item for Retrieve Port Group Configuration Construct Item for Add Virtual Switch Construct Item for Add Virtual NIC Construct Item for Add Port Group Construct Item for Remove Virtual Switch Construct Item for Remove Virtual NIC Construct Item for Remove Port Group Construct Item for Add NAS Datastore Construct Item for Add Vmfs Datastore Construct Item for Add Internet SCSI Send Targets Construct Item for Retrieve Available Disks For Vmfs Construct Item for Retrieve Host CPU Construct Item for Retrieve Host Memory Construct Item for Retrieve ESX Hosts Construct Item for Retrieve Host Scsi Topology Constructs Items XML for the Create Host wrapper Constructs Items XML for the Move Host to Cluster wrapper Constructs Items XML for the Add Host to Cluster wrapper Constructs Items XML for the Remove Host from Cluster wrapper Constructs Items XML for the Update Host Network Configuration wrapper Constructs Items XML for the Retrieve Host Configuration wrapper Constructs Items XML for the Retrieve Host DVS Configuration wrapper Constructs Items XML for the Retrieve Host Network Configuration wrapper Constructs Items XML for the Retrieve Host Datastore Configuration wrapper Constructs Items XML for the Retrieve Virtual Switch Configuration wrapper Constructs Items XML for the Retrieve Virtual NIC Configuration wrapper Constructs Items XML for the Retrieve Port Group Configuration wrapper Constructs Items XML for the Add Virtual Switch wrapper Constructs Items XML for the Add Virtual NIC wrapper Constructs Items XML for the Add Port Group wrapper Constructs Items XML for the Remove Virtual Switch wrapper Constructs Items XML for the Remove Virtual NIC wrapper Constructs Items XML for the Remove Port Group wrapper Constructs Items XML for the Add NAS Datastore wrapper Constructs Items XML for the Add Vmfs Datastore wrapper Constructs Items XML for the Add Internet SCSI Send Targets wrapper Constructs Items XML for the Retrieve Available Disks For Vmfs wrapper Constructs Items XML for the Retrieve Host CPU wrapper Constructs Items XML for the Retrieve Host Memory wrapper Constructs Items XML for the Retrieve ESX Hosts wrapper Constructs Items XML for the Retrieve Host Scsi Topology wrapper
739
Construct Item for Rescan Hba Construct Item for Rescan All Hba Construct Item for Extend Vmfs Datastore Construct Item for Update Software Internet SCSI Enabled Construct Item for Update Internet SCSI Name Construct Item for Remove Datastore Construct Item for Enter Maintenance Mode Construct Item for Exit Maintenance Mode Datastore operations Construct Item for Retrieve Datastore List Construct Item for Retrieve Datastore Virtual Machines Construct Item for Retrieve Vmfs Datastore Storage Controller Cluster Operations Construct Item for Retrieve Cluster Configuration Construct Item for Retrieve Cluster Datastore Configuration Construct Item for Retrieve Clusters Datacenter operations Construct Item for Retrieve Datacenters Folder operations Construct Item for Create Folder Construct Item for Retrieve Folders Construct Item for Destroy Folder Discovery operations Construct Item for Retrieve MOB Reference By Display Name Construct Item for Retrieve Display Name By MOB Reference Resource Pool operations Construct Item for Retrieve Resource Pool Children Configure VApp operations Construct Item for Export VApp as OVF Template
Constructs Items XML for the Rescan Hba wrapper Constructs Items XML for the Rescan All Hba wrapper Constructs Items XML for the Extend Vmfs Datastore wrapper Constructs Items XML for the Update Software Internet SCSI Enabled wrapper Constructs Items XML for the Update Internet SCSI Name wrapper Constructs Items XML for the Remove Datastore wrapper Constructs Items XML for the Enter Maintenance Mode wrapper Constructs Items XML for the Exit Maintenance Mode wrapper
Constructs Items XML for the Retrieve Datastore List wrapper Constructs Items XML for the Retrieve Datastore Virtual Machines wrapper Constructs Items XML for the Retrieve Vmfs Datastore Storage Controller wrapper
Constructs Items XML for the Retrieve Cluster Configuration wrapper Constructs Items XML for the Retrieve Cluster Datastore Configuration wrapper Constructs Items XML for the Retrieve Clusters wrapper
Constructs Items XML for the Retrieve Datacenters wrapper
Constructs Items XML for the Create Folder wrapper Constructs Items XML for the Retrieve Folders wrapper Constructs Items XML for the Destroy Folder wrapper
Constructs Item XML for the Retrieve MOB Reference By Display Name wrapper Constructs Item XML for the Retrieve Display Name By MOB Reference wrapper
Constructs Item XML for the Retrieve Resource Pool Children wrapper
Constructs Item XML for the Export VApp as OVF Template wrapper
740
Construct Item for Import OVF Template as VApp Construct Item for Create VApp Construct Item for Clone VApp Construct Item for Update VApp Configuration
Constructs Item XML for the Import OVF Template as VApp wrapper Constructs Item XML for the Create VApp wrapper Constructs Item XML for Clone VApp wrapper Constructs Item XML for the Update VApp Configuration wrapper
Version directories for the VMware Infrastructure adapter

The v3.0 directory contains processes specific to VMware Infrastructure 3.0. The v4.0 directory contains processes specific to VMware vSphere 4.0. A process is available for each supported operation. Processes are grouped in sub-directories based on the operation type. Note You can use the constructor processes to generate complex XML inputs that are consumed by the functional processes. For more information about constructor processes, see Utilities directory.
Process Inputs for the VMware Infrastructure adapter module

This section provides information about the process input elements for the processes in the adapter module. The following table describes the input elements used by a wrapper process in the adapter module. Process Input elements Inputs adapter name items Description The name of the adapter that will handle this request The Items XML used to perform the wrapper process Required No Yes No
connection-parameters Contains the information needed for the adapter to connect to the target <connection-parameters> contains the <user-name> and <password> elements.
You can obtain the Items XML for a wrapper process by using the corresponding constructor process in Development Studio. Example For the Create Host wrapper process, you can obtain the Items XML by using the Construct Create Host Item process in the Utilities folder in Project Explorer of the Development Studio.
You can also create a sample Items XML from the adapter requests detailed in this document in Actor adapter requests and responses for the VMware Infrastructure adapter. For example, a sample adapter request for the Create_Host operation, as specified in this document, is illustrated in the following code sample:
741
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Create_Host</operation-name> <user-name></user-name> <password></password> <parameters> <folder>TestHostFolder</folder> <datacenter>BMC</datacenter> <spec> <force>false</force> <host-name>abc.bmc.com</host-name> <password></password> <port></port> <user-name>root</user-name> <vim-account-name></vim-account-name> <vim-account-password></vim-account-password> <folder>vm</folder> </spec> <add-connected>false</add-connected> </parameters> </vmware-infrastructure-request>
You can obtain a sample Items XML for the Create Host wrapper process by: Replacing the <vmware-infrastructure-request> tag with <items><item> tags Replacing the </vmware-infrastructure-request> tag with </item></items> tags Removing the <operation-type>, <operation-name>, <user-name>, and {{<password>}}tags The sample Items XML obtained from the sample Create_Host operation is illustrated in the following code sample.
<items> <item> <parameters> <folder>TestHostFolder</folder> <datacenter>BMC</datacenter> <spec> <force>false</force> <host-name>abc.bmc.com</host-name> <password></password> <port></port> <user-name>root</user-name> <vim-account-name></vim-account-name> <vim-account-password></vim-account-password> <folder>vm</folder> </spec> <add-connected>false</add-connected> </parameters> </item> <items>
VMWare home page

742
The application adapter enables BMC Atrium Orchestrator workflow processes to perform specialized functions and to interact with VMware Infrastructure by providing an interface between the workflow processes and VMware Infrastructure. BMC Atrium Orchestrator application adapter for VMware Infrastructure consists of an actor, an event monitor and an SNMP monitor adapter and workflow processes.
Actor adapter
The actor adapter executes operations on VMware Infrastructure by using the VMware SDK API. To execute the operations, the adapter invokes Web Service calls on the VMware SDK API. The actor adapter can perform the following categories of operations: Basic VM operations Basic VApp operations Advanced VM operations Configure VM operations Monitor VM operations Host operations Cluster operations Datacenter operations Datastore operations Discovery operations Folder operations Resource Pool operations Configure VApp operations
Monitor adapter
The event monitor adapter uses the VMware SDK API to listen for events, including Vmotion events, that are generated on VMware Infrastructure. The SNMP monitor adapter listens to the SNMP traps sent by VMware Virtual Center.
Note VMware Virtual Center must be configured to send SNMP traps to the BMC Atrium Orchestrator peer on which the adapter is enabled.
An event is evaluated by rules and can trigger specific workflow processes when the rule criteria are met.
Actor adapter requests and responses for the VMware Infrastructure adapter
The adapter requests for the actor adapter uses a set of elements, operation-type and operation-name, in the adapter request node to execute an API call. The set of values used to make each API call is referred to as an operation. You can use the information in this topic with the Call Adapter activity to create an adapter request. For detailed instructions about how to use the Call Adapter activity, see Call Adapter activity and Creating and configuring the Call Adapter activity. The adapter can perform the following categories of operations:
743
Basic VM operations Basic VApp operations Advanced VM operations Configure VM operations Monitor VM operations Host operations Datastore operations Cluster operations Datacenter operations Folder operations Discovery operations Resource Pool operations VApp Configuration operations Adapter operations with VMware Infrastructure Operation Type Sub-folder (if applicable) Basic_Vm Power_On_VM Powers on the virtual machine and boots the guest OS, if the guest OS is installed Powers off the virtual machine The virtual machine does not attempt to shut down the guest operating system (OS) gracefully. Pauses the virtual machine activity All transactions are frozen until the virtual machine gets a Resume command. Allows virtual machine activity to continue when the virtual machine is in suspended state Shuts down and restarts the guest OS Shuts down the guest OS gracefully Shuts down and restarts the guest OS without powering off the virtual machine Starts the specified vApp Stops the specified vApp Operation name Description
Basic_Vm
Power_Off_VM
Basic_Vm
Suspend_VM
Basic_Vm
Resume_VM
Basic_Vm Basic_Vm Basic_Vm
Reset_VM Shut_Down_Guest_OS Restart_Guest_OS
Basic_VApp Basic_VApp
Power_On_VApp Power_Off_VApp
744
Basic_VApp
Unregister_VApp
Removes the vApp from the inventory without removing any of the files associated with the relevant virtual machines from the disk Creates a snapshot of the specified virtual machine Reverts the current virtual machine to a specified snapshot Relocates the virtual disks of a virtual machine to the specific location Checks the validity of proposed VM migration before conducting the actual migration Migrates a virtual machine execution to a specific resource pool or host Relocates the virtual disks for a virtual machine to a specified location You can also use this operation to move a virtual machine to a different datastore or a different host. Creates and returns a one-time usable credential for establishing a remote mouse-keyboard-screen connection to the specified virtual machine Returns details about the files that match the specified search criteria Updates the name and description of the snapshot Removes the specified snapshot and deletes any storage associated with the snapshot. Creates a new virtual machine with specified configuration parameters
Advanced_Vm Advanced_Vm
Create_VM_Snapshot Revert_VM_Snapshot
Advanced_Vm
Move_Virtual_Disk
Advanced_VM
Validate_VM_Migration
Advanced_Vm
Migrate_VM
Advanced_Vm
Relocate_VM
Advanced_Vm
Acquire_Mks_Ticket
Advanced_Vm
Retrieve_VM_File_Info
Advanced_Vm Advanced_Vm
Update_VM_Snapshot Delete_VM_Snapshot
Configure_VM
Create_VM
745
Configure_VM
Create_VM_With_Custom_Settings
Creates a new virtual machine with advanced configuration options This operation enables you to add virtual devices like a hard disk or an ethernet card while creating the virtual machine. Clones a VM with the same configuration as the specified virtual machine This operation can also be used to clone a VM into a template. Clones a virtual machine with advanced configuration options This operation can also be used to clone a virtual machine into a template. This operation enables you to add additional virtual devices such as a hard disk or an ethernet card to the cloned virtual machine. Adds a virtual disk on the specified virtual machine Adds an ethernet adapter to the specified virtual machine Adds the specified CD-ROM device to the specified virtual machine Retrieves the specified virtual machine configuration parameters Retrieves the configuration details of the CPU for the specified virtual machine Retrieves the memory configuration details for the specified virtual machine Retrieves the configuration details of the hard disk for the specified virtual machine Retrieves the configuration details of the ethernet adapter for the specified virtual machine
Configure_VM
Clone_VM
Configure_VM
Clone_VM_With_Custom_Settings
Configure_VM Configure_VM
Add Hardware Add Hardware Add Hardware
Add_Hard_Disk Add_Ethernet_Adapter
Configure_VM
Add_CD_ROM
Configure_VM
Retrieve_VM_Configuration
Configure_VM
Retrieve Hardware Retrieve Hardware Retrieve Hardware
Retrieve_CPU_Configuration
Configure_VM
Retrieve_Memory_Configuration
Configure_VM
Retrieve_Hard_Disk_Configuration
Configure_VM
Retrieve Hardware
Retrieve_Ethernet_Adapter_Configuration
746
Configure_VM
Retrieve Hardware
Retrieve_CD_ROM_Configuration
Retrieves the configuration of a CD-ROM device for the specified virtual machine Modifies one or more configuration parameters for a virtual machine This operation can be used to add or remove a hard disk, CD-ROM, or an ethernet adapter from a virtual machine. Attaches a previously uploaded ISO file to the specified CD or the DVD drive Modifies the CPU configuration of a virtual machine This operation can modify the CPU configuration of a virtual machine, even if the machine is in the Power On or the Suspended state. Modifies the memory configuration of a virtual machine. This operation can modify the virtual machine's memory configuration, even if the machine is in the Power On or the Suspended state. Modifies the ethernet adapter configuration on a virtual machine This operation can modify the virtual machine's ethernet adapter configuration, even if the machine is in the Power On or the Suspended state. Enables you to increase the size of the hard disk attached to a virtual machine This operation can also update the disk shares information. Deletes the specified virtual machine
Configure_VM
Update_VM_Configuration
Configure_VM
Update Hardware
Update_CD_ROM_Configuration
Configure_VM
Update Hardware
Update_CPU_Configuration
Configure_VM
Update Hardware
Update_Memory_Configuration
Configure_VM
Update Hardware
Update_Ethernet_Adapter_Configuration
Configure_VM
Update Hardware
Update_Hard_Disk_Configuration
Configure_VM
Delete_VM
747
Configure_VM
Export_VM_As_OVF_Template
Exports the specified virtual machine as an OVF template and downloads the files associated with the VM entity Creates a new virtual machine in the resource pool based on the specified OVF descriptor Removes the specified ethernet adapter from a virtual machine This operation must be performed only when the virtual machine is in the Powered Off state. Removes the specified virtual disk from a virtual machine Removes the specified CD_ROM device from a virtual machine Retrieves the status of a specific task performed on a virtual machine by task ID Retrieves the list of alarms, including their state, for the specified virtual machine Retrieves the CPU usage for the last collection interval from the specified virtual machine The returned results are for average, minimum, and maximum, and are expressed in 0.01% percentage points (value is from 0 to 10,000). Retrieves the sum of the data read and written for all disk instances of the host or virtual machine Results returned are for average, minimum, and maximum, and expressed in Kbps.
Configure_VM
Import_OVF_Template_As_VM
Configure_VM
Remove Hardware
Remove_Ethernet_Adapter
Configure_VM
Remove Hardware Remove Hardware
Remove_Hard_Disk
Configure_VM
Remove_CD_ROM
Monitor_Vm
Retrieve_Task_Status
Monitor_Vm
Retrieve_VM_Alarm_List
Monitor_Vm
Retrieve_VM_CPU_Usage
Monitor_Vm
Retrieve_VM_Disk_Usage
748
Monitor_Vm
Retrieve_VM_Memory Usage
Retrieves the current memory in use for the specified virtual machine Results returned are for average, minimum, and maximum, and are expressed in 0.01% percentage points (value is from 0 to 10,000). Removes the alarm from the list of alarms affecting the specified virtual machine Retrieves the sum of data transmitted and received for all the NIC instances of the specified virtual machine Retrieves the operating status for the specified virtual machine Adds an ESX server to a specified cluster on the VMware Virtual Center The hostname provided should be a DNS resolvable name. For example, host1.domain1.com Add an ESX server to the VMware Virtual Center The name of the host must be specified as a string. Updates the configuration of the host network to add a virtual switch Updates the configuration of the host network to add a virtual NIC Updates the configuration of the host network to add a port group Creates a new storage datastore attached to the network Adds a new VMFS datastore to an ESX Server. Adds Send Target entries to the host bus adapter discovery list.
Monitor_Vm
Delete_VM_Alarm
Monitor_Vm
Retrieve_VM_Network Usage
Monitor_Vm
Retrieve_VM_Status
Host
Add_Host_To_Cluster
Host
Create_Host
Host
Add Networking Hardware Add Networking Hardware Add Networking Hardware
Add_Virtual_Switch
Host
Add_Virtual_NIC
Host
Add_Port_Group
Host
Add_NAS_Datastore
Host
Add_Vmfs_Datastore
Host
Add_Internet_Scsi_Send_Targets
749
Host
Move_Host_To Cluster
Moves the specified host into a specified cluster The host must be part of the same datacenter, and if the host is part of a cluster, the host must be in maintenance mode. Retrieves the configuration details of the host computer including allocated and utilized CPU and memory Retrieves the DV Switch and DV Portgroup configured on the specified ESX host Retrieves the host network configuration details including details about the virtual switch, virtual NIC, and port group Retrieves the configuration details of the host datastore Retrieves the configuration details of the host network virtual switch Retrieves the configuration details of the host network virtual NIC Retrieves the configuration details of the host network port group Retrieves a list of disks that can be used to contain new VMFS datastores Retrieves CPU information and current CPU usage on the specified host system Retrieves the memory size and current memory usage for the specified host system Retrieves the known ESX hosts and configuration on a VMware VirtualCenter, filtered by the specified cluster
Host
Retrieve_Host_Configuration
Host
Retrieve_Host_DVS_Configuration
Host
Retrieve_Host_ Network_Configuration
Host
Retrieve_Host_Datastore_Configuration
Host
Retrieve Networking Hardware Retrieve Networking Hardware Retrieve Networking Hardware
Retrieve_Virtual_Switch_Configuration
Host
Retrieve_Virtual_NIC_Configuration
Host
Retrieve_Port_Group_Configuration
Host
Retrieve_Available_Disks_For_Vmfs
Host
Retrieve_Host_CPU_Usage
Host
Retrieve_Host_Memory_Usage
Host
Retrieve_ESX_Hosts
750
Host
Retrieve_Host_Scsi_Topology
Retrieves the storage topology of SCSI storage devices for the specified host This topology view organizes objects by SCSI interface, which contain targets, which in turn contain logical units. Issues a request for rescanning the specified host bus adapter on an ESX Server to detect new storage devices Issues a request to rescan all host bus adapters on a ESX server for detecting new storage devices Updates the network configuration of a host Extends an existing VMFS datastore Enables or disables an Internet SCSI Updates the name of an Internet SCSI host bus adapter Removes a host from a cluster and makes it a standalone host Updates the configuration of the host network to remove a virtual switch Updates the configuration of the host network to remove a virtual NIC Updates the configuration of the host network to remove a port group Removes a datastore from a host system Puts the specified host in the maintenance mode Takes the specified host out of the maintenance mode
Host
Rescan_Hba
Host
Rescan_All_Hba
Host Host Host Host
Update_Host_Network_Configuration Extend_Vmfs_Datastore Update_Software_Internet_Scsi_Enabled Update_Internet_Scsi_Name
Host
Remove_Host_From Cluster
Host
Remove Networking Hardware Remove Networking Hardware Remove Networking Hardware
Remove_ Virtual_ Switch
Host
Remove_ Virtual_ NIC
Host
Remove_ Port_ Group
Host Host Host
Remove_Datastore Enter_Maintenance_Mode Exit_Maintenance_Mode
751
Datastore
Retrieve_Datastore_List Retrieves a list of datastores on a datacenter including information about the total space and free space available on each datastore
Datastore
Retrieve_Datastore_Virtual Machines
Retrieves a list of all virtual machines registered on the specified datastore Retrieves the volume information for the specified VMFS datastore and corresponding SCSI transport information about the target Retrieves the configuration details for a cluster including DRS settings Retrieves the configuration details for a datastore of the cluster including total space and free space. Retrieves all known clusters and configuration on a VMware VirtualCenter Retrieves the known datacenters and configuration on a VMware VirtualCenter. Creates a sub-folder within a folder, with the specified name Retrieves all the folders and the corresponding configuration on a VMware VirtualCenter, filtered by datacenter Destroys the specified folder object by deleting the contents of the folder and removing the folder from the parent folder, if the parent folder exists
Datastore
Retrieve_Vmfs_Datstore_Storage_Controller
Cluster
Retrieve_Cluster_Configuration
Cluster
Retrieve_Cluster_Datastore_Configuration
Cluster
Retrieve_Clusters
Datacenter
Retrieve_Datacenters
Folder
Create_Folder
Folder
Retrieve_Folders
Folder
Destroy_Folder
Discovery
Retrieve_MOB_Reference_By_Display_Name Retrieves the Managed Object Reference for a VMware Infrastructure element using the display name
752
Discovery
Retrieve_Display_Name_By_MOB_Reference Retrieves the display name, type, and the datacenter name of a VMware Infrastructure element using the Managed Object Reference of the element Retrieve_Resource_Pool_Children Retrieves a list of all child resource pools associated with the specified resource pool Exports the specified VApp as an OVF template and downloads the files that are associated with the VApp entity Creates a new VApp in the resource pool based on the specified OVF descriptor Creates a new vApp container Creates a new VApp container from the specified VApp Updates the configuration of the specified vApp
ResourcePool
Configure_VApp
Export_VApp_As_OVF_Template
Configure_VApp
Import_OVF_Template_As_VApp
Configure_VApp Configure_VApp
Create_VApp Clone_VApp
Configure_VApp
Update_VApp_Configuration
Note To override the default adapter configuration, you must specify the required arguments in the adapter requests. The Basic VApp and the Configure VApp operations are supported with VMware vSphere 4.0.
Adapter requests and responses for Basic VM operations

The following topics illustrate the adapter requests and responses for the Basic VM operations.
Request and response for the Power_On_VM operation Request and response for the Power_Off_VM operation Request and response for the Suspend_VM operation Request and response for the Resume_VM operation Request and response for the Reset_VM operation Request and response for the Restart_Guest_OS operation Request and response for the Shut_Down_Guest_OS operation
Request and response for the Power_On_VM operation

The Power_On_VM operation powers on the virtual machine and boots the guest operating system, if the guest operating system is installed. The following table describes the elements for this request.
753
Adapter request elements for Power_On_VM operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Power_On_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name password Contains the data types and elements of the operation Contains the name of the virtual machine on which the Power On operation is to be executed If no user name is specified, the request is executed with user specified in the configuration The password corresponding to the specified user name
No
Yes Yes No Conditional Required if the user-name element is provided
The following code sample shows a sample adapter request for the Power_On_VM operation. Sample adapter request for the Power_On_VM operation
754
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Power_On_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample illustrates the response for the sample Power_ON_VM operation. Sample adapter response for the Power_On_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <PowerOnVM_TaskResponse> <Task>task-709</Task> </PowerOnVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Power_On_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Power_Off_VM operation

This operation powers off the virtual machine. The virtual machine does not attempt to shut down the guest OS gracefully. The following table describes the elements for this request. Adapter request elements for Power_Off_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Power_Off_VM.
755
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
parameters virtual-machine user-name password
Contains the data types and elements of the operation Specifies the virtual machine on which the Power Off operation is to be executed If no user name is specified, the request is executed with user specified in the configuration The password corresponding to the specified user name
The following code sample shows a sample adapter request for the Power_Off_VM operation. Sample adapter request for the Power_Off_VM operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Power_Off_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
756
The following code sample shows the response for the sample Power_Off_VM operation. Sample adapter response for the Power_Off_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <PowerOffVM_TaskResponse> <Task>task-710</Task> </PowerOffVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Power_Off_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Suspend_VM operation

This operation pauses the virtual machine activity. All transactions remain in the frozen state, until the virtual machine gets a Resume command. The following table describes the elements for this request. Adapter request elements for the Suspend_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Suspend_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
757
transport
No
Contains the data types and elements of the operation Contains the name of the virtual machine on which the Suspend operation is to be executed If no user name is specified, the request is executed with user specified in the configuration The password corresponding to the specified user name
The following code sample shows the sample adapter request for the Suspend_VM operation. Sample adapter request for the Suspend_VM operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Suspend_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Suspend_VM operation. Sample adapter response for the Suspend_VM operation
758
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <SuspendVM_TaskResponse> <Task>task-712</Task> </SuspendVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Suspend_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Resume_VM operation

This operation allows the activity of the virtual machine to continue when the virtual machine is in a suspended state.
The following table describes the elements for this request. Adapter request elements for the Resume_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Resume_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
759
transport
No
Contains the data types and elements of the operation Contains the name of the virtual machine on which the Resume operation is to be executed If no user name is specified, the request is executed with user specified in the configuration The password corresponding to the specified user name
The following code sample shows a sample adapter request for the Resume_VM operation. Sample adapter request for the Resume_VM operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Resume_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Resume_VM operation. Sample adapter response for the Resume_VM operation
760
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ResumeVM_TaskResponse> <Task>task-719</Task> </ResumeVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Resume_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Reset_VM operation

This operation shuts down the guest operating system of a virtual machine and restarts it. Note For this operation to execute, the guest operating system and VMTools must be installed on the virtual machine.
The following table describes the elements for this request. Adapter request elements for the Reset_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Reset_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
761
transport
No
parameters virtual-machine user-name
Contains the data types and elements of the operation Contains the name of the virtual machine on which the Reset operation is to be executed The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
Conditional Required if the user-name element is provided
The following code sample shows the sample adapter request for the Reset_VM operation. Sample adapter request for the Reset_VM operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Reset_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Reset_VM operation. Sample adapter response for the Reset_VM operation
762
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ResetVM_TaskResponse> <Task>task-711</Task> </ResetVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Reset_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Restart_Guest_OS operation

This operation shuts down and restarts the guest operating system without powering off the virtual machine. The following table describes the elements for this request. Adapter request elements for the Restart_Guest_OS operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Restart_Guest_OS. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
763
transport
No
Contains the data types and elements of the operation Contains the name of the virtual machine on which the Restart Guest OS operation is to be executed The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Restart_Guest_OS operation. Sample adapter request for the Restart_Guest_OS operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Restart_Guest_OS</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Restart_Guest_OS operation. Sample adapter response for the Restart_Guest_OS operation
764
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RebootGuestResponse> </RebootGuestResponse> </vmware-infrastructure-response>
Request and response for the Shut_Down_Guest_OS operation

This operation shuts down the guest operating system without powering off the virtual machine. The following table describes the elements for this request. Adapter request elements for the Shut_Down_Guest_OS operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Shut_Down_Guest_OS. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Contains the name of the virtual machine on which the Shut Down Guest OS operation is to be executed
No
Yes Yes
765
user-name
The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
password
The following code sample shows a sample adapter request for the Shut_Down_Guest_OS operation. Sample adapter request for the Shut_Down_Guest_OS operation
<vmware-infrastructure-request> <operation-type>Basic_Vm</operation-type> <operation-name>Shut_Down_Guest_OS</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Shut_Down_Guest_OS operation. Sample adapter response for the Shut_Down_Guest_OS operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ShutdownGuestResponse> </ShutdownGuestResponse> </vmware-infrastructure-response>
Adapter requests and responses for Advanced VM operations

The following topics illustrates the adapter requests and responses for the Advanced VM operations.
Request and response for the Create_VM_Snapshot operation Request and response for the Revert_VM_Snapshot operation Request and response for the Move_Virtual_Disk operation Request and response for the Validate_VM_Migration operation Request and response for the Migrate_VM operation Request and response for the Relocate_VM operation Request and response for the Acquire_Mks_Ticket operation Request and response for the Retrieve_VM_File_Info operation
766
Request and response for the Update_VM_Snapshot operation Request and response for the Delete_VM_Snapshot operation
Request and response for the Create_VM_Snapshot operation

This operation creates a snapshot of the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Create_VM_Snapshot operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Create_VM_Snapshot. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine name description memory Contains the data types and elements of the operation Contains the name of the virtual machine on which the snapshot is to be created The name for this snapshot The name need not be unique for this virtual machine. A description of the snapshot
No
Yes Yes Yes No
Indicates whether to include a memory dump in a snapshot Yes Valid values: true, false If 'true', a memory dump of the internal state of the virtual machine is included in the snapshot. If 'false', the power state of the snapshot is set to powered off.
767
quiesce
Indicates if the quiesce flag is active Valid values: true, false If 'true' and the virtual machine is powered on when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. This ensures that a disk snapshot represents a consistent state of the guest file systems. If the virtual machine is powered off or VMware Tools are not available, the quiesce flag is ignored. The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
Yes
user-name
No
password
The following code sample shows a sample adapter request for the Create_VM_Snapshot operation. Sample adapter request for the Create_VM_Snapshot operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Create_VM_Snapshot</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <name>winSS1</name> <description>from WS</description> <memory>true</memory> <quiesce>false</quiesce> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Create_VM_Snapshot operation. Sample adapter response for the Create_VM_Snapshot operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateSnapshot_TaskResponse> <Task>task-719</Task> </CreateSnapshot_TaskResponse> </vmware-infrastructure-response>
768
The following table describes the response element. Adapter response element for the Create_VM_Snapshot operation Element Definition Task Task ID of the submitted Task
Request and response for the Revert_VM_Snapshot operation

This operation reverts the current virtual machine to a specified snapshot. The following table describes the elements for this request. Note Do not specify the virtual machine name in the canonical path; specify only the snapshot.
Adapter request elements for the Revert_VM_Snapshot operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Revert_VM_Snapshot. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation
No
Yes
769
virtual-machine name
Contains the name of the virtual machine on which the snapshot is to be reverted The canonical path name for the snapshot Since the name may not be unique for this virtual machine, you must specify the complete canonical path The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Revert_VM_Snapshot operation. Sample adapter request for the Revert_VM_Snapshot operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Revert_VM_Snapshot</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <name>win1SnapShot/sun1SnapShot/sun1SnapShot</name> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Revert_VM_Snapshot operation. Sample adapter response for the Revert_VM_Snapshot operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RevertToSnapshot_TaskResponse> <Task>task-720</Task> </RevertToSnapshot_TaskResponse> </vmware-infrastructure-response>
The following code sample describes the response element. Adapter response element for the Revert_VM_Snapshot operation Element Definition
770
Task
Task ID of the submitted Task
Request and response for the Move_Virtual_Disk operation

This operation relocates the virtual disks of a virtual machine to a specific location. The following table describes the elements for this request. Note This operation is not supported for virtual machines that carry snapshots.
Adapter request elements for the Move_Virtual_Disk operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Move_Virtual_Disk. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Contains the name of the virtual machine whose virtual disks is to be moved
No
No
Yes Yes
771
disk-list
Specifies the datastore location for each virtual disk Sample value:
<disk-list> <disk> <datastore></datastore> <disk-name></disk-name> <disk> <disk> <datastore></datastore> <disk-name></disk-name> </disk> </disk-list>
Yes
datastore: target datastore for the virtual disk disk-name: device name of the virtual disk datacenter Specifies the datacenter hosting the datastore Conditional Required if the datastore with the same name exists across Datacenters No
transform
Transformation to perform on the disks If it is not valid for the current operation, the backend ignores this element. This can be used by clients, for example, to create sparse disks for templates. Valid values: flat, sparse The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
user-name
No
password
The following code sample shows a sample adapter request for the Move_Virtual_Disk operation. Sample adapter request for the Move_Virtual_Disk operation
772
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Move_Virtual_Disk</operation-name> <user-name></user-name> <password></password> <soap-url></soap-url> <transport></transport> <parameters> <virtual-machine>win1</virtual-machine> <spec> <disk-list> <disk> <disk-name>Disk1</disk-name> <datastore>storage1</datastore> </disk> <disk> <disk-name>Disk2</disk-name> <datastore>storage2</datastore> </disk> </disk-list> <transform>flat</transform> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Move_Virtual_Disk operation. Sample adapter response for the Move_Virtual_Disk operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <MoveVirtualDiskResponse> <Task>task-1403</Task> </MoveVirtualDiskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Move_Virtual_Disk operation Element Definition Task Task ID of the submitted Task
Request and response for the Validate_VM_Migration operation

This operation verifies the validity of the proposed virtual machine migration, before performing the actual migration. The following table describes the elements for this request.
773
Adapter request elements for the Validate_VM_Migration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Validate_VM_Migration. soap-url
Specifies the URL for the remote SOAP service running on the VMware No VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
transport
No
parameters virtual-machine resource-pool
Contains the data types and elements of the operation Contains the name of the virtual machine intended to be migrated Specifies the target resource pool for the virtual machine If the resource-pool parameter is not specified, the target pool for the virtual machine's migration is the current pool of the virtual machine. Valid value: String
Yes Yes Conditional Required if the host-system element is not specified Conditional Required if the resource-pool element is not specified
host-system
DNS name of the target host on which the virtual machine will run Valid value: host name If the compute resource associated with the target pool represents a stand-alone host or a DRS-enabled cluster, the host parameter is not specified. For a stand-alone host, the host is used as the target host. For a DRS-enabled cluster, every connected host in the cluster that is not in maintenance mode is tested as a target host.
774
test-type-list
The set of tests to run If this argument is not set, all tests will be executed. Valid values: compatibilityTests, diskAccessibilityTests, resourceTests, sourceTests Sample value:
<test-type-list> <test-type> </test-type> <test-type> </test-type> </test-type-list>
No
state
The power state that the virtual machine must have If this element is not specified, the virtual machine is evaluated according to its current power state. Valid values: poweredOff, poweredOn, suspended The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
user-name
No
password
The following code sample shows a sample adapter request for the Validate_VM_Migration operation. Sample adapter request for the Validate_VM_Migration operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Validate_VM_Migration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <state>poweredOn</state> <test-type-list> <test-type>compatibilityTests</test-type> <test-type>resourceTests</test-type> </test-type-list> <resource-pool>TestRP</resource-pool> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Validate_VM_Migration operation.
775
Sample adapter response for the Validate_VM_Migration operation

<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ValidateMigrationResponse> <MigrationErrorEvent> <key>0</key> <chainId>0</chainId> <createdTime>2008-01-01T13:48:13.613125Z</createdTime> <userName>Administrator</userName> <datacenter> <name>Development</name> <Datacenter>datacenter-2</Datacenter> </datacenter> <computeResource> <name>xyz.bmc.com</name> <ComputeResource>domain-s175</ComputeResource> </computeResource> <host> <name>xyz.bmc.com</name> <HostSystem">host-8</HostSystem> </host> <vm> <name>win1</name> <VirtualMachine>vm-14</VirtualMachine> </vm> <fullFormattedMessage>Migration completed.'ng5.abc.com'.</fullFormattedMessage>
<te
The following table describes the response element. Adapter response element for the Validate_VM_Migration operation Element Definition Events A set of events describing the warnings or errors that would be applicable, if the proposed set of migrations were executed.
Request and response for the Migrate_VM operation

This operation migrates a virtual machine's execution to a specific resource pool or host. The following table describes the elements for this request. Adapter request elements for the Migrate_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Migrate_VM.
776
soap-url
Specifies the URL for the remote SOAP service running on the VMware No VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
transport
No
parameters virtual-machine resource-pool
Contains the data types and elements of the operation Contains the name of the virtual machine intended for migration Specifies the resource pool for the virtual machine If the resource-pool parameter is not specified, the target pool for the virtual machine's migration is the current pool of the virtual machine. Valid value: String
Yes Yes Conditional Required if the host-system element is not specified. Conditional Required if the resource-pool element is not specified. Yes No No
host-system
DNS name of the target host on which the virtual machine runs Valid value: host name If the compute resource associated with the target pool represents a stand-alone host or a DRS-enabled cluster, the host parameter is not specified. For a stand-alone host, the host is used as the target host. For a DRS-enabled cluster, every connected host in the cluster that is not in maintenance mode is tested as a target host. The priority of the migration task Valid values: defaultPriority, highPriority, lowPriority The power state of the virtual machine Valid values: poweredOff, poweredOn, suspended The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
priority state user-name
password
777
The following code sample shows a sample adapter request for the Migrate_VM operation. Sample adapter request for the Migrate_VM operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Migrate_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <resource-pool>TestRP</resource-pool> <host-system>xyz.bmc.com</host-system> <priority>defaultPriority</priority> <state>poweredOff</state> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Migrate_VM operation. Sample adapter response for the Migrate_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <MigrateVM_TaskResponse> <Task>task-721</Task> </MigrateVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Migrate_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Relocate_VM operation

This operation enables you to relocate the virtual disks for a virtual machine to a specified location. In addition, you can also use this operation to move a virtual machine to a different datastore or a different host. The following table describes the elements for this request. Adapter request elements for the Relocate_VM operation Element Definition Required
778
operation-type
Defines the type of the operation For this operation, the value of operation-type is Advanced_Vm.
Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Relocate_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine datacenter Contains the data types and elements of the operation Specifies the name of the virtual machine that you want to migrate Valid value: String Specifies the name of the datacenter hosting the relevant datastore
No
Yes Yes Conditional Required if the datstore with the same name exists across datacenters
datastore
Specifies the datastore to which you want to relocate the VM By default, the VM is relocated to the same datastore.
No
779
disk-list
Specifies the datastore location for each virtual disk XML sample
<disk-list> <disk> <datastore></datastore> <disk-name></disk-name> <disk-move-type></disk-move-type> <disk> <disk> <datastore></datastore> <disk-name></disk-name> <disk-move-type></disk-move-type> </disk> </disk-list>
No
datastore: target datastore for the virtual disk disk-name: device name of the virtual disk disk-move-type Specifies the approach to be used for moving the virtual disk to the target datastore No The valid values for this element are: createNewChildDiskBacking: Create a new child disk backing on the destination datastore. The existing files on the virtual disk are not moved from thier current location. moveAllDiskBackingsAndAllowSharing: All the backings for the virtual disk are moved to the new datastore. If a disk backing is not the child-most backing of this virtual machine, and there exists a read-only disk backing with the same content ID on the target datastore, this disk backing is not copied. Instead, it is acceptable to attach to the read-only disk backing at the target datastore. A read-only disk backing is defined as a virtual disk backing. moveAllDiskBackingsAndDisallowSharing: All backings for the virtual disk is moved to the new datastore. It is not acceptable to attach to a disk backing with the same content ID on the destination datastore. moveChildMostDiskBacking: Move only the child-most disk backing. Any parent disk backings are left in their current location. This option only differs from moveAllDiskBackingsAndAllowSharing and moveAllDiskBackingsAndDisallowSharing when the virtual disk has a parent backing.
Note: This property applies to all the disks which the virtual machine has, but can be overridden on a per-disk basis using diskMoveType. This property can only be set if deltaDiskBackingsSupported is true at HostSystem level. By default, the adapter uses moveAllDiskBackingsAndDisallowSharing. The disk-move-type element is supported only in VMware vSphere 4.0.
780
host-system
Specifies the DNS name of the target host on which the virtual machine runs Valid value: host name If the compute resource associated with the target pool represents a stand-alone host or a DRS-enabled cluster, the host parameter is not specified. For a stand-alone host, the host is used as the target host. For a DRS-enabled cluster, every connected host in the cluster that is not in maintenance mode is tested as a target host. Specifies the transformation to perform on the disks If the transformation is not valid for the current operation, the value specified in this element is . This element can be used to create sparse disks for templates. Valid values: flat, sparse The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
transform
No
user-name
No
password
The following code sample shows a sample adapter request for the Relocate_VM operation. Sample adapter request for the Relocate_VM operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Relocate_VM</operation-name> <parameters> <virtual-machine>TestVm</virtual-machine> <datacenter>Datacenter1</datacenter> <spec> <datastore>storage1</datastore> <disk-list> <disk> <disk-name>Hard disk 1</disk-name> <datastore>storage2</datastore> <disk-move-type>moveChildMostDiskBacking</disk-move-type> </disk> <disk> <disk-name>Hard disk 2</disk-name> <datastore>storage3</datastore> <disk-move-type>moveChildMostDiskBacking</disk-move-type> </disk> </disk-list> <disk-move-type>moveChildMostDiskBacking</disk-move-type> <host-system>ESXHost1</host-system> <transform>flat</transform> </spec> </parameters> </vmware-infrastructure-request>
781
The following code sample shows the response for the sample Relocate_VM operation. Sample adapter response for the Relocate_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RelocateVM_TaskResponse> <Task>task-53</Task> </RelocateVM_TaskResponse> </vmware-infrastructure-response>
The following code sample describes the response element. Adapter response element for the Relocate_VM operation Element Definition Task Task ID of the submitted Task
Request and response for the Acquire_Mks_Ticket operation

This operation creates and returns a one-time usable credential for establishing a remote mouse-keyboard-screen connection to the specified virtual machine. Note This operation works correctly depending on the retrieval of the TCP binding information pertaining to the server end of the client connection requesting the ticket. If the required TCP binding information is not available, a Not Supported fault is generated. This method is appropriate for SOAP and authenticated connections, which are TCP-based connections.
The following table describes the elements for this request. Adapter request elements for the Acquire_Mks_Ticket operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Acquire_Mks_Ticket.
782
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
Contains the data types and elements of the operation The name of the virtual machine used to make the method call Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes No
password
Conditional Required if user-name is provided.
The following code sample shows a sample adapter request for the Acquire_Mks_Ticket operation. Sample adapter request for the Acquire_Mks_Ticket operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Acquire_Mks_Ticket</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>TestDev156</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Acquire_Mks_Ticket operation.
783
Sample adapter response for the Acquire_Mks_Ticket operation

<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AcquireMksTicketResponse> <returnval> <ticket>52ee9b9c-d347-b956-d93d-57c87d921c07</ticket> <cfgFile>/vmfs/volumes/48287d4e-aec12ab6-1d350019b9e1c5fe/TestDev156_1/TestDev156.vmx</cfgFile> <host>dev151.bmc.com</host> <port>902</port> </returnval> </AcquireMksTicketResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Acquire_Mks_Ticket operation Element Definition cfgFile host The name of the configuration file for the virtual machine The host to which the connection is to be established If the host is not specified, it is assumed that the requesting entity knows the appropriate host to connect. The port number to use If the port is not specified, it is assumed that the requesting entity knows the appropriate port to use when making a new connection. The ticket name This element is used as the username and password for the MKS connection.
port
ticket
Request and response for the Retrieve_VM_File_Info operation

This operation returns details about the files that match the specified search criteria. The operation searches the folder specified by the datastore and all corresponding subfolders. The Vmware client used by the operation must have at least browse access to the specified datastore. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_File_Info operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Advanced_Vm. Required Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_VM_File_Info.
Yes
784
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
parameters datastore
Contains the data types and elements of the operation Contains the name of the datastore to search for files matching the given criteria Valid value: String Specifies the datacenter hosting the datastore This element is only required if duplicate datastores exist in different datacenters with the same name. Contains the name of the virtual machine used to make the method call Valid value: String
Yes Yes
datacenter
Conditional
virtual-machine
No If this element is not specified, the file information for all virtual machines in the datastore are retrieved. No
match-pattern
Contains the criteria for searching files in the datastore For virtual machine disk files, you can obtain the actual size of the disk file by specifying flat in the match pattern. Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
user-name
No
password
Conditional Required if user-name is provided
785
The following code sample shows a sample adapter request for the Retrieve_VM_File_Info operation. Sample adapter request for the Retrieve_VM_File_Info operation
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Retrieve_VM_File_Info</operation-name> <soap-url></soap-url> <transport></transport <user-name></user-name> <password></password> <parameters> <datastore>abc15 disk3</datastore> <virtual-machine>TestVM6</virtual-machine> <search-spec> <match-pattern>*.vmdk</match-pattern> </search-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_File_Info operation. Sample adapter response for the Retrieve_VM_File_Info operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMFileInfoResponse> <returnval> <Task>session[E421C3ED-FCC7-4BA2-93D8-1E7562B9BC06]2E8B024F-0048-4681-8A4A-546F96871866</Task> <propSet> <name>info</name> <TaskInfo> <key>session[E421C3ED-FCC7-4BA2-93D8-1E7562B9BC06]2E8B024F-0048-4681-8A4A-546F96871866</key> <Task>session[E421C3ED-FCC7-4BA2-93D8-1E7562B9BC06]2E8B024F-0048-4681-8A4A-546F96871866</Task> <name>SearchDatastoreSubFolders_Task</name> <descriptionId>host.DatastoreBrowser.searchSubFolders</descriptionId> <Datacenter>datacenter-2</Datacenter> <entityName>ABC_DEV</entityName> <state>success</state> <cancelled>false</cancelled> <cancelable>false</cancelable> <ArrayOfHostDatastoreBrowserSearchResults> <HostDatastoreBrowserSearchResults> <Datastore>datastore-15</Datastore> <folderPath>[abc15 disk3] TestVM6/</folderPath> <file> <path>TestVM6-flat.vmdk</path> <fileSize>5144576000</fileSize> <modification>2009-10-12T07:27:02-04:00</modification>
786
</file> <file> <path>TestVM6.vmdk</path> <fileSize>396</fileSize> <modification>2009-10-13T07:10:39-04:00</modification> </file> <file> <path>TestVM6_1-flat.vmdk</path> <fileSize>5144576000</fileSize> <modification>2009-10-12T07:29:39-04:00</modification> </file> <file> <path>TestVM6_1.vmdk</path> <fileSize>398</fileSize> <modification>2009-10-13T07:10:40-04:00</modification> </file> </HostDatastoreBrowserSearchResults> </ArrayOfHostDatastoreBrowserSearchResults> <TaskReasonUser> <userName>rba</userName> </TaskReasonUser> <queueTime>2009-12-28T06:13:32.6875Z</queueTime> <startTime>2009-12-28T06:13:32.6875Z</startTime> <completeTime>2009-12-28T06:13:32.8125Z</completeTime> <eventChainId>0</eventChainId> </TaskInfo> </propSet>
787
</returnval> </RetrieveVMFileInfoResponse> </vmware-infrastructure-response>
The following code sample describes the adapter response elements. Adapter response elements for the Retrieve_VM_File_Info operation Element Task cancelable cancelled Definition A task is used to monitor and potentially cancel long running operations Flag to indicate whether or not the cancel task operation is supported Flag to indicate whether or not the client requested cancellation of the task
completeTime Time stamp when the task was completed (whether success or failure) descriptionId An identifier for this operation This includes publicly visible internal tasks and is a lookup in the TaskDescription methodInfo data object. Managed entity to which the operation applies The name of the managed entity, locale-specific, retained for the history collector database If the task state is error, this property contains the fault code. Event chain ID that leads to the corresponding events If the state of the task is running, this property is a list of managed entities that the operation has locked, with a shared lock. The name of the operation that created the task This is not set for internal tasks. If the task state is running, this property contains a progress measurement, expressed as percentage completed, from 0 to 100. If this property is not set, the command does not report progress. Time stamp when the task was created Kind of entity responsible for creating this task If the task state is success, this property may contain a return value Time stamp when the task started running Runtime status of the task The managed object that represents this task
entity entityName error eventChainId locked name progress
queueTime reason result startTime state task
Request and response for the Update_VM_Snapshot operation

This operation updates the name and description of the snapshot. With this operation, you need to specify either the name or description of the snapshot to be updated. The following table describes the elements for this request. Adapter request elements for the Update_VM_Snapshot operation
788
Element operation-type
Definition Defines the type of operation For this operation, the value of operation-type is Advanced_Vm.
Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Update_VM_Snapshot. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine name Contains the data types and elements of the operation The name of the virtual machine from which the snapshot is to be updated Valid value: String Contains the name of the snapshot to be updated The name need not be unique for the specified virtual machine. Valid value: String Contains the new name for the snapshot Valid value: String Contains the new description for the snapshot Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes Yes
new-name description user-name
No No No
password
The following codes sample shows a sample adapter request for the Update_VM_Snapshot operation. Sample adapter request for Update_VM_Snapshot operation
789
<vmware-infrastructure-request> <operation-type>Advanced_Vm</operation-type> <operation-name>Update_VM_Snapshot</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>TestDev156</virtual-machine> <name>NewSnapshot</name> <new-name>UpdatedSnapshot</new-name> <description>updated description</description> </parameters> </vmware-infrastructure-request>
The following codes sample shows the response for the sample Update_VM_Snapshot operation. Sample adapter response for Update_VM_Snapshot operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RenameSnapshotResponse></RenameSnapshotResponse> </vmware-infrastructure-response>
Request and response for the Delete_VM_Snapshot operation

This operation removes the specified snapshot and deletes any storage associated with the snapshot. The following table describes the elements for this request. Adapter request elements for Delete_VM_Snapshot operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Advanced_Vm. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Delete_VM_Snapshot. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
790
transport
Specifies the transport protocol for the message. If the transport element is not No provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
Contains the data types and elements of the operation The name of the virtual machine from which the snapshot will be deleted Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name.
Yes Yes No
password
name
Specifies the parent/child hierarchy of the snapshot that must be deleted If the snapshot is a child snapshot, the value of the name element must be expressed in terms of the root snapshot. For example, to delete the VM snapshot "SNAP_67890000", which is the child snapshot of "SNAP_12345000", you need to specify the parent/child hierarchy as follows: <name>SNAP_12345000/SNAP_67890000</name> If the snapshot to be deleted is several levels below the parent snapshot, you must specify the complete path, starting with the parent snapshot, including all the intermediate levels, and the snapshot that you wish to delete. Tip Use the Request and response for the Retrieve_VM_Configuration operation to see the root/child relationship in a given VM.
Yes
The name need not be unique for the specified virtual machine. Valid value: Any string
791
remove-children Indicates whether to remove the entire snapshot subtree
Yes
Warning If you specify remove-children as true and specify only a root snapshot in <name>, all the snapshots from the VM are deleted. Valid values: true, false
The following code sample shows a sample adapter request for the Delete_VM_Snapshot operation to delete VM snapshot "SNAP_67890000": Sample adapter request for Delete_VM_Snapshot operation
<vmware-infrastructure-request> <operation-type>Advanced_VM</operation-type> <operation-name>Delete_VM_Snapshot</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>TestDev156</virtual-machine> <name>SNAP_12345000/SNAP_67890000</name> <remove-children>true</remove-children> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Delete_VM_Snapshot operation. Sample adapter response for Delete_VM_Snapshot operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveSnapshot_TaskResponse> <Task>task-6932</Task> </RemoveSnapshot_TaskResponse> </vmware-infrastructure-response>
Adapter requests and responses for Configure VM operations

The following topics illustrate the adapter requests and responses for the Configure VM operations.
Request and response for the Create_VM operation Request and response for the Create_VM_With_Custom_Settings operation Request and response for the Clone_VM operation Request and response for the Clone_VM_With_Custom_Settings operation Request and response for the Add_Hard_Disk operation
792
Request and response for the Retrieve_VM_Configuration operation Request and response for the Add_Ethernet_Adapter operation Request and response for the Add_CD_ROM operation Request and response for the Retrieve_CPU_Configuration operation Request and response for the Retrieve_Memory_Configuration operation Request and response for the Retrieve_Hard_Disk_Configuration operation Request and response for the Retrieve_CD_ROM_Configuration operation Request and response for the Retrieve_Ethernet_Adapter_Configuration operation Request and response for the Update_CD_ROM_Configuration operation Request and response for the Update_VM_Configuration operation Request and response for the Update_CPU_Configuration operation Request and response for the Update_Memory_Configuration operation Request and response for the Update_Ethernet_Adapter_Configuration operation Request and response for the Update_Hard_Disk_Configuration operation Request and response for the Delete_VM operation Request and response for the Remove_Hard_Disk operation Request and response for the Remove_Ethernet_Adapter operation Request and response for the Remove_CD_ROM operation Request and response for the Export_VM_As_OVF_Template operation Request and response for the Import_OVF_Template_As_VM operation
Request and response for the Create_VM operation

This operation creates a new virtual machine with the specified configuration parameters. The following table describes the elements for this request. Adapter request elements for the Create_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Create_VM. Required Yes
operation-name
Yes
soap-url
Specifies the URL for the remote SOAP service No running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http:// hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
793
transport
No
parameters
Contains the data types and elements of the operation
Yes No Mandatory if <resource-pool> is not specified No
cluster-compute-resource The cluster compute resource to which the host-system is attached folder Specifies the folder in which the new virtual machine needs to be created If this element is not specified, the virtual machine is created in the default vm folder. The resource pool to which the virtual machine will be attached
resource-pool
No Mandatory if <cluster-compute-resource> is not specified No If the virtual machine is to be added to the default resource pool of the host and the host is a stand-alone host, the host-system element is mandatory.
host-system
DNS name of the target host on which the virtual machine will run This must specify a host that is a member of the ComputeResource indirectly specified by the pool. For a stand-alone host or a cluster with DRS, the host can be omitted and the system selects a default. Valid value: host name The name of the datacenter where the virtual machine has to be created Display name of the virtual machine
datacenter name
Yes Yes
794
guest-id
Short guest operating system identifier If you do not specify a guest ID, the new virtual machine can not be used. For example, the Power On, Edit Settings cannot be performed on the VM since the Guest OS assigned is UNKNOWN.
Yes
For more information about guest operating system identifiers, see Guest operating system identifiers for VMware Infrastructure. datastore-location Datastore location to the configuration for the virtual machine For example, the .vmx file The datastore location also implicitly defines the configuration directory. Number of virtual processors in a virtual machine Valid value: Number Size of a virtual machine's memory, in MB Valid value: Number Yes
num-cpus memory-mb user-name
No No
The name of the user No If no user name is specified, the request executes with the user specified in the configuration. The password associated with the user-name provided Conditional If the user-name element is provided
password
The following code sample shows a sample adapter request for the Create_VM operation. Sample adapter request for the Create_VM operation
795
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Create_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <resource-pool>TestRP</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <folder>NewVM</folder> <datacenter>BMC_DEV</datacenter> <config> <name>Linux16</name> <guest-id>rhel4Guest</guest-id> <files> <datastore-location>storage1</datastore-location> </files> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> </config> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Create_VM operation. Sample adapter response for the Create_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateVM_TaskResponse> <Task>task-723</Task> </CreateVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Create_VM operation Element Definition Task Task ID of the submitted task
Request and response for the Create_VM_With_Custom_Settings operation

This operation creates a new virtual machine with advanced configuration options. This operation enables you to add virtual devices like a hard disk or an ethernet card for a newly created virtual machine. The following table describes the elements for this request.
796
Adapter request elements for the Create_VM_With_Custom_Settings operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Create_VM_With_Custom_Settings. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. TThe default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http:// hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation Yes Yes Mandatory if <resource-pool> is not specified. No No Required Yes
operation-name
Yes
soap-url
No
cluster-compute-resource The cluster compute resource to which the host-system is attached
folder
Specifies the folder in which the new virtual machine needs to be created If this element is not specified, the virtual machine is created in the default vm folder. Specifies the resource pool for the virtual machine If the pool parameter is not specified, the target pool for virtual machine's migration is the current pool of the virtual machine
resource-pool
No Mandatory if <cluster-compute-resource> is not specified
797
host-system
DNS name of the target host on which the virtual machine will run This must specify a host that is a member of the ComputeResource indirectly specified by the pool. For a stand-alone host or a cluster with DRS, the host can be omitted, and the system selects a default. Valid value: host name The display name of the virtual machine The name of the datacenter where the virtual machine has to be created The version string for the virtual machine User-provided description of the virtual machine Short identifier for the guest operating system Note: If you do not specify a guest ID, the new virtual machine can not be used. For example, the Power On, Edit Settings cannot be performed on the VM since the Guest OS assigned is UNKNOWN. For more information about short identifiers for guest operation systems, see Guest operating system identifiers for VMware Infrastructure. Datastore location to the configuration for the virtual machine For example, the .vmx file. This also implicitly defines the configuration directory. The configuration of VMware tools running on the guest operating system For more information about the child elements, see tools . Encapsulates the flag settings for a virtual machine For more information about the child elements, see flags .
No
name datacenter version annotation guest-id
Yes Yes No No No
datastore-location
Yes
tools
No
flags
No
console-preferences
Preferences for the legacy console application that affect No the way it behaves during power operations on the virtual machine For more information about the child elements, see console-preferences. Configuration for default power operations For more information about the child elements, see power-op-info. The number of virtual processors in a virtual machine Size of a virtual machine's memory, in MB Set of virtual devices being added by the operation Operations supported: add For more information about the child elements, see device-change-list for adding devices. Note: To add a hard disk or an ethernet adapter, you must also add the corresponding controller. No
power-op-info
num-cpus memory-mb device-change-list
No No No
798
cpu-allocation
Specifies the resource limits for the CPU For more information about the child elements, see cpu-allocation. Specifies the resource limits for memory For more information about the child elements, see memory-allocation. A list of nodes, processors for a CPU that can be used by the virtual machine If the array is empty when modifying the affinity setting, then any existing affinity is removed. List of nodes (NUMA nodes for memory) that can be used by the virtual machine If the array is empty when modifying the affinity setting, any existing affinity is removed the network traffic shaping specification Traffic shaping is used to configure the network utilization characteristics of a virtual machine. For information about child elements, see network-shaper Specifies the CPU feature compatibility masks For more information about the child elements, see cpu-feature-mask-list.
No
memory-allocation
No
cpu-affinity
No
memory-affinity
No
network-shaper
No
cpu-feature-mask-list
No
user-name
The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name Conditional Required if the user-name element is provided
password
The following code sample shows a sample adapter request for the Create_VM_With_Custom_Settings operation. Sample adapter request for the Create_VM_With_Custom_Settings operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Create_VM_With_Custom_Settings</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <resource-pool>TestRP</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <folder>NewVMFolder</folder> <datacenter>BMC_DEV</datacenter> <config> <name>Linux16</name> <version>vmx-04</version> <guest-id>rhel4Guest</guest-id> <annotation>Test Linux machine</annotation>
799
<files> <datastore-location>storage1</datastore-location> </files> <tools> <tools-version></tools-version> <after-power-on>false</after-power-on> <after-resume>false</after-resume> <before-guest-standby>false</before-guest-standby> <before-guest-shutdown>false</before-guest-shutdown> <before-guest-reboot>false</before-guest-reboot> </tools> <flags> <disable-acceleration>true</disable-acceleration> <enable-logging>false</enable-logging> <use-toe>false</use-toe> <run-with-debug-info>true</run-with-debug-info> <ht-sharing>any</ht-sharing> </flags> <console-preferences> <power-on-when-opened>true</power-on-when-opened> <enter-full-screen-on-power-on>false</enter-full-screen-on-power-on> <close-on-power-off-or-suspend>true</close-on-power-off-or-suspend> </console-preferences> <power-op-info> <power-off-type>soft</power-off-type> <suspend-type>soft</suspend-type> <reset-type>soft</reset-type> <default-power-off-type>soft</default-power-off-type> <default-suspend-type>soft</default-suspend-type> <default-reset-type>soft</default-reset-type> <standby-action>checkpoint</standby-action> </power-op-info> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> <device-change-list> <device-change> <operation>add</operation> <device type="VirtualBusLogicController"> <bus-number>0</bus-number> <device>0</device> <shared-bus>noSharing</shared-bus> </device> </device-change> <device-change> <operation>add</operation> <file-operation>create</file-operation> <device type="VirtualDisk"> <backing type="VirtualDiskFlatVer2BackingInfo"> <file-name>[dev15 disk2]</file-name> <disk-mode>persistent</disk-mode> <split>true</split> <write-through>true</write-through> <thin-provisioned>false</thin-provisioned> </backing> <controller-key>0</controller-key> <unit-number>-1</unit-number>
800
<capacity-inKB>1024</capacity-inKB> <shares> <shares>1024</shares> <level>custom</level> </shares> </device> </device-change> <device-change> <operation>add</operation> <device type="VirtualPCIController"> <bus-number>0</bus-number> <device>0</device> </device> </device-change> <device-change> <operation>add</operation> <device type="VirtualPCNet32"> <backing type="VirtualEthernetCardNetworkBackingInfo"> <device-name>VM Network</device-name> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>true</allow-guest-control> <connected>false</connected> </connectable> <controller-key>0</controller-key> <unit-number>0</unit-number> <address-type>manual</address-type> <mac-address>00:50:56:84:2f:6b</mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> <cpu-allocation> <reservation>0</reservation> <limit>-1</limit> <shares> <shares>1862</shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <reservation>0</reservation> <limit>2048</limit> <shares> <shares>2048</shares> <level>custom</level> </shares> </memory-allocation> <cpu-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </cpu-affinity> <memory-affinity>
801
<affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </memory-affinity> <network-shaper> <enabled>true</enabled> <peak-bps>10</peak-bps> <average-bps>5</average-bps> <burst-size>8</burst-size> </network-shaper> <cpu-feature-mask-list> <cpu-feature-mask> <operation>add</operation> <info> <level>-2147483648</level> <vendor>amd</vendor> <eax></eax> <ebx></ebx> <ecx></ecx> <edx></edx> </info> </cpu-feature-mask> </cpu-feature-mask-list> </config>
802
<host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Create_VM_With_Custom_Settings operation with thin provisioning. Sample adapter request for the Create_VM_With_Custom_Settings operation with thin provisioning
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Create_VM_With_Custom_Settings</operation-name> <parameters> <resource-pool>TestRPool</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <folder>NewVMFolder</folder> <datacenter>BMC_DEV</datacenter> <config> <name>Linux16</name> <version></version> <guest-id>rhel4Guest</guest-id> <annotation>Test Linux machine</annotation> <files> <datastore-location>dev1 disk2</datastore-location> </files> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> <device-change-list> <device-change> <operation>add</operation> <device type="VirtualBusLogicController"> <bus-number>0</bus-number> <device>0</device> <shared-bus>noSharing</shared-bus> </device> </device-change> <device-change> <operation>add</operation> <fileOperation>create</fileOperation> <device type="VirtualDisk"> <backing type="VirtualDiskFlatVer2BackingInfo"> <fileName>[dev1 disk2]</fileName> <diskMode>persistent</diskMode> <split>true</split> <writeThrough>true</writeThrough> <thinProvisioned>true</thinProvisioned> </backing> <connectable> <start-connected>true</start-connected> <allow-guest-control>true</allow-guest-control> <connected>true</connected> </connectable>
803
<controllerKey>0</controllerKey> <unitNumber>-1</unitNumber> <capacityInKB>1024</capacityInKB> <shares> <shares>1024</shares> <level>custom</level> </shares> </device> </device-change> </device-change-list> </config>
804
<host-system>xyz.abc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Create_VM_With_Custom_Settings operation. Sample adapter response for the Create_VM_With_Custom_Settings operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateVM_TaskResponse> <Task>task-723</Task> </CreateVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Create_VM_With_Custom_Settings operation Element Definition Task Task ID of the submitted task
Request and response for the Clone_VM operation

This operation is used to clone a virtual machine with the same configuration as a specified virtual machine. In addition, this operation can be used to clone a virtual machine into a template. The following table describes the elements for this request. Adapter request elements for the Clone_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Clone_VM.
805
soap-url
No
transport
No
parameters virtual-machine folder datacenter name power-on
Contains the data types and elements of the operation Contains the name of the virtual machine intended to be cloned Specifies the folder in which the clone must be created If this element is not specified, the clone is created in the default vm folder. The name of the datacenter where the clone is to be created Display name of the virtual machine Specifies whether the new virtual machine should be powered on after creation As part of the customization, this flag is normally set to true, since the first power-on operation completes the customization process. This flag is ignored if a template is being created. valid values: true, false Specifies whether the new virtual machine must be marked as a template valid values: true, false The location of resources that the newly cloned virtual machine will use Datastore is a mandatory tag. For more information about the child elements, see location.
Yes Yes No Yes Yes Yes
template location
Yes Conditional If the virtual machine is being cloned from a template No Conditional If the user-name element is provided
user-name password
The name of the user. If no user name is specified, the request executes with the user specified in the configuration. The password associated with the user-name provided
The following code sample shows a sample adapter request for the Clone_VM operation.
806
Sample adapter request for the Clone_VM operation

<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Clone_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <folder></folder> <datacenter>Development</datacenter> <name>win8</name> <spec> <power-on>false</power-on> <template>false</template> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Clone_VM operation. Sample adapter response for the Clone_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CloneVM_TaskResponse> <Task>task-724</Task> </CloneVM_TaskResponse> </vmware-infrastructure-response>
The following code sample shows a sample adapter request for the Clone_VM operation, to clone a virtual machine from a template. Sample adapter request for the Clone_VM operation
807
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Clone_VM</operation-name> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <folder></folder> <datacenter>Development</datacenter> <name>win8</name> <spec> <power-on>false</power-on> <template>false</template> <location> <resource-pool>TestRP</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <host-system>xyz.bmc.com </host-system> <datastore>storage1</datastore> <transform>flat</transform> <disk-list> <disk> <disk-name>Hard Disk 1</disk-name> <datastore>storage1</datastore> </disk> </disk-list> </location> </spec> </parameters> </vmware-infrastructure-request>
The following table describes the response element. Adapter response element for the Clone_VM operation Element Definition Task Task ID of the submitted task
Request and response for the Clone_VM_With_Custom_Settings operation

This operation is used to clone a virtual machine with advanced configuration options. In addition, this operation can also be used to clone a virtual machine into a template. This operation enables you to add additional virtual devices like a hard disk or an ethernet card to the cloned virtual machine. This operation also supports the customization of the guest operating system on a virtual machine. The following table describes the elements for this request. Adapter request elements for the Clone_VM_With_Custom_Settings operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes
808
operation-name
Defines the name of the operation For this operation, the value of operation-name is Clone_VM_With_Custom_Settings. Contains the data types and elements of the operation Contains the name of the virtual machine intended to be cloned The folder in which the cloned virtual machine must be created If this element is not specified, the cloned virtual machine is created in the default vm folder. Specifies the datacenter in which the cloned virtual machine is to be created The name of the new virtual machine Specifies whether to power on the new virtual machine, after creation As part of a customization, this flag is generally set to true, since the first power-on operation completes the customization process. This flag is ignored if a template is being created. Valid values: true, false The location of resources that the newly cloned virtual machine will use. Datastore is an optional element. For more information about the child elements, see location. Specifies whether the new virtual machine should be marked as a template Display name of the virtual machine The version string for the virtual machine Short identifier for the guest operating system If the guest operating system is not specified, the virtual machine is cloned with the same operating system as the original virtual machine. For more information about short identifiers for guest operation systems, see Guest operating system identifiers for VMware Infrastructure. User-provided description of the virtual machine The configuration of VMware tools running on the guest operating system For more information about the child elements of tools, see tools. Encapsulates the flag settings for a virtual machine For more information about the child elements, see flags. Preferences for the legacy console application that affect the way it behaves during power operations on the virtual machine For more information about the child elements, see console-preferences. Configuration for default power operations For more information about the child elements, see power-op-info. Number of virtual processors in the virtual machine Memory size of the virtual machine, in MB Valid values: Number
Yes
parameters virtual-machine folder
Yes Yes No
datacenter name power-on
Yes Yes Yes
location
Conditional If the virtual machine is being cloned from a template. Yes Yes No No
template name version guest-id
annotation tools
No No
flags console-preferences
No No
power-op-info num-cpus memory-mb
No No No
809
device-change-list
Set of virtual devices being added by the configuration operation Operations supported: add For more information about the child elements, see device-change-list for adding devices. Resource limits for the CPU For more information about the child elements, see cpu-allocation.
No
cpu-allocation memory-allocation memory-affinity
No
Resource limits for memory No For more information about the child elements, see memory-allocation. List of nodes (NUMA nodes for memory) that can be used by the virtual machine If the array is empty when modifying the affinity setting, then any existing affinity is removed. the network traffic shaping specification Traffic shaping is used to configure the network utilization characteristics of a virtual machine. For information about child elements, see network-shaper No
network-shaper
No
cpu-feature-mask-list Specifies the CPU feature compatibility masks For more information about the child elements, see cpu-feature-mask-list. customization Specifies the details for customizing the guest operating system of the virtual machine For more information about the child elements, see customization.
No
No
soap-url
Specifies the URL for the remote SOAP service running on the No VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
transport
No
user-name
The name of the user If no user name is specified, the request executes with the user specified in the configuration.
No
810
password
The password associated with the user-name provided
Conditional If the user-name element is provided
The following code sample shows a sample adapter request for the Clone_VM_With_Custom_Settings operation. Sample adapter request for the Clone_VM_With_Custom_Settings operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Clone_VM _With_Custom_Settings</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <folder>TestVMFolder</folder> <datacenter>Development</datacenter> <name>win8</name> <spec> <power-on>false</power-on> <template>false</template> <location> <resource-pool>TestRP</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <host-system>xyz.abc.com</host-system> <datastore>storage1</datastore> <transform>flat</transform> <disk-list> <disk> <disk-name>Hard Disk 1</disk-name> <datastore>storage1</datastore> </disk> </disk-list> </location> <config> <name>win8</name> <version>vmx-04</version> <guest-id> rhel4Guest</guest-id> <annotation>Test Linux machine</annotation> <tools> <tools-version></tools-version> <after-power-on>true</after-power-on> <after-resume>false</after-resume> <before-guest-standby>true</before-guest-standby> <before-guest-shutdown>true</before-guest-shutdown> <before-guest-reboot>false</before-guest-reboot> </tools> <flags> <disable-acceleration>true</disable-acceleration> <enable-logging>false</enable-logging>
811
<use-toe>false</use-toe> <run-with-debug-info>true</run-with-debug-info> <ht-sharing>any</ht-sharing> </flags> <console-preferences> <power-on-when-opened>true</power-on-when-opened> <enter-full-screen-on-power-on>false</enter-full-screen-on-power-on> <close-on-power-off-or-suspend>true</close-on-power-off-or-suspend> </console-preferences> <power-op-info> <power-off-type>soft</power-off-type> <suspend-type>soft</suspend-type> <reset-type>soft</reset-type> <default-power-off-type>soft</default-power-off-type> <default-suspend-type>soft</default-suspend-type> <default-reset-type>soft</default-reset-type> <standby-action>checkpoint</standby-action> </power-op-info> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> <device-change-list> <device-change> <operation>add</operation> <device type="VirtualBusLogicController"> <bus-number>0</bus-number> <device>0</device> <shared-bus>noSharing</shared-bus> </device> </device-change> <device-change> <operation>add</operation> <fileOperation>create</fileOperation> <device type="VirtualDisk"> <backing type="VirtualDiskFlatVer2BackingInfo"> <fileName>[dev1 disk2]</fileName> <diskMode>persistent</diskMode> <split>true</split> <writeThrough>true</writeThrough> <thinProvisioned>false</thinProvisioned> </backing> <controllerKey>0</controllerKey> <unitNumber>-1</unitNumber> <capacityInKB>1024</capacityInKB> <shares> <shares>1024</shares> <level>low</level> </shares> </device> </device-change> <device-change> <operation>add</operation> <device type="VirtualPCIController"> <bus-number>0</bus-number> <device>0</device> </device> </device-change>
812
<device-change> <operation>add</operation> <device type="VirtualPCNet32"> <backing type="VirtualEthernetCardNetworkBackingInfo"> <device-name>VM Network</device-name> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>true</allow-guest-control> <connected>false</connected> </connectable> <controllerKey>0</controllerKey> <unitNumber>0</unitNumber> <address-type>manual</address-type> <mac-address>00:50:56:84:2f:6b</mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> <cpu-allocation> <reservation>0</reservation> <limit>-1</limit> <shares> <shares>1862</shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <reservation>0</reservation> <limit>2048</limit> <shares> <shares>2048</shares> <level>custom</level> </shares> </memory-allocation> <cpu-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </cpu-affinity> <memory-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </memory-affinity> <network-shaper> <enabled>true</enabled> <peak-bps>10</peak-bps> <average-bps>5</average-bps> <burst-size>8</burst-size> </network-shaper> <cpu-feature-mask-list> <cpu-feature-mask> <operation>add</operation>
813
<info> <level>-2147483648</level> <vendor>amd</vendor> <eax></eax> <ebx></ebx> <ecx></ecx> <edx></edx> </info> </cpu-feature-mask> <cpu-feature-mask> <operation>add</operation> <info> <level>-2147483647</level> <vendor></vendor> <eax>----:----:---0:----:----:----:----:----</eax> <ebx></ebx> <ecx></ecx> <edx></edx> </info> </cpu-feature-mask> </cpu-feature-mask-list> </config> <customization> <identity type='CustomizationSysprep'> <gui-unattended> <password> <value>abc123</value> <plain-text>true</plain-text> </password> <time-zone>123</time-zone> <auto-logon>false</auto-logon> <auto-logon-count>1</auto-logon-count> </gui-unattended> <user-data> <full-name>User1</full-name> <org-name>BMC</org-name> <computer-name> <name>AdapterDev</name> </computer-name> <product-id></product-id> </user-data> <identification> <join-workgroup>WORKGROUP</join-workgroup> </identification> <license-file-print-data> <auto-mode></auto-mode> <auto-users></auto-users> </license-file-print-data> </identity> <globalIPSettings> <dns-server-list> <dns-server-list>10.254.1.10</dns-server-list>
814
<dns-server-list>10.254.1.11</dns-server-list> </dns-server-list> <dns-suffix-list> <dns-suffix-list>abc.com</dns-suffix-list> <dns-suffix-list>vmware.com</dns-suffix-list> </dns-suffix-list> </globalIPSettings> <nic-setting-map> <adapter> <ip type="CustomizationDhcpIpGenerator"> <ipAddress></ipAddress> </ip> <subnet-mask>255.255.255.0</subnet-mask> <gateway>172.1.114.1</gateway> <dns-domain>abc.com</dns-domain> </adapter> </nic-setting-map> </customization>
815
</spec> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Clone_VM_With_Custom_Settings operation with thin provisioning for the virtual disk. Sample adapter request for the Clone_VM_With_Custom_Settings operation with thin provisioning
816
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Clone_VM_With_Custom_Settings</operation-name> <parameters> <virtual-machine>win1</virtual-machine> <folder>TestVMFolder</folder> <datacenter>Test</datacenter> <name>win8</name> <spec> <power-on>false</power-on> <template>false</template> <location> <host-system>xyz.abc.com</host-system> </location> <config> <device-change-list> <device-change> <operation>add</operation> <device type="VirtualBusLogicController"> <key>0</key> <bus-number>0</bus-number> <device>0</device> <shared-bus>noSharing</shared-bus> </device> </device-change> <device-change> <operation>add</operation> <fileOperation>create</fileOperation> <device type="VirtualDisk"> <key>0</key> <backing type="VirtualDiskFlatVer2BackingInfo"> <fileName>[dev1 disk2]</fileName> <diskMode>persistent</diskMode> <split>true</split> <writeThrough>true</writeThrough> <thinProvisioned>true</thinProvisioned> </backing> <controllerKey>0</controllerKey> <unitNumber>-1</unitNumber> <capacityInKB>1024</capacityInKB> <shares> <shares>1024</shares> <level>low</level> </shares> </device> </device-change> </device-change-list> </config> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Clone_VM_With_Custom_Settings operation.
817
Sample adapter response for the Clone_VM_With_Custom_Settings operation

<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CloneVM_TaskResponse> <Task>task-724</Task> </CloneVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Clone_VM_With_Custom_Settings operation Element Definition Task Task ID of the submitted task.
Request and response for the Add_Hard_Disk operation

This operation enables you to add a hard disk on the specified virtual machine. Note This operation also allows you to set up a flag to indicate that the virtual disk backing file must be allocated using thin provisioning. You can use this flag only for the file systems that support configuring the provisioning policy on a per file basis, such as VMFS3.
The following table describes the elements for this request. Adapter request elements for the Add_Hard_Disk operation Element operation-type Definition Specifies the type of the operation: Configure_Vm Required Yes Yes No
operation-name Specifies the name of the operation: Add_Hard_Disk soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If <soap-url> is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. Default value format for HTTPS: https://hostName:port/sdk/vim Default value format for HTTP: http://hostName:port/sdk/vim Note: If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
818
transport
Specifies the transport protocol for the message If <transport> is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. Valid values: https-rp, http-rpc (default) Note: If the value of <transport> is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. Contains the data types and elements of the operation Specifies the virtual machine to which a hard disk is to be added File name for the host file used in the operation Note: The file name must be enclosed in square brackets. Contains information about the hard disk that you want to add The valid values for the controller-type attribute of this element are: VirtualBusLogicController (default) VirtualLsiLogicController VirtualLsiLogicSASController ParaVirtualSCSIController
No
parameters virtual-machine file-name device
Yes Yes Yes Yes
disk-mode
The disk persistence mode Valid values: persistent independent_persistent independent_nonpersistent nonpersistent
Yes
split
Flag to indicate the type of virtual disk file: split or monolithic Valid values: true, false If true, the virtual disk is stored in multiple 2-GB files.
No
thin-provisioned Flag to indicate to the underlying file system whether the virtual disk backing file No should be allocated using thin provisioning This flag is used only for file systems that support configuring the provisioning policy on a per file basis, such as VMFS3. Valid values: true, false (default) By default, the virtual disk backing file is allocated using thick provisioning. write-through Flag to indicate whether disk write operations go directly to the file system or buffer Valid values: true, false The capacity of the virtual disk The number of shares allocated This value is used to determine the resource allocation in case of resource contention. This value is set only if <level> is set to custom; otherwise, this value is ignored. Hence, only <shares> with <custom> values can be compared. There is no unit for this value. It is a relative measure based on the settings for other resource pools. Valid values: Any positive number No
capacity-inKB shares
Yes No
819
level
Indicates the allocation level The level is a simplified view of <shares>. Levels map to a predetermined set of numeric values for shares. If the value of <shares> does not map to a predefined size, then <level> is set as custom. Valid values: custom Shares are specified in the "shares" column. high low normal
No
user-name
The name of the user If <user-name> is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified <user-name>
No
password
Conditional; required if <user-name> is provided
The following code sample shows a sample adapter request for the Add_Hard_Disk operation. Sample adapter request for the Add_Hard_Disk operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Add_Hard_Disk</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <device-change> <device controller-type="VirtualBusLogicController"> <backing> <file-name>[storage1]</file-name> <disk-mode>persistent</disk-mode> <split></split> <write-through></write-through> <thin-provisioned></thin-provisioned> </backing>> <capacity-inKB>20480</capacity-inKB> <shares> <shares>1024</shares> <level>custom</level> </shares> </device> </device-change> </spec> </parameters> </vmware-infrastructure-request>
820
The following code sample shows a sample adapter request for the Add_Hard_Disk operation with thin provisioning.
Sample adapter request for the Add_Hard_Disk operation with thin provisioning
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Add_Hard_Disk</operation-name> <parameters> <virtual-machine>LinuxVM_Temp</virtual-machine> <spec> <device-change> <device> <backing> <file-name>[Storage1]</file-name> <disk-mode>persistent</disk-mode> <split>true</split> <write-through></write-through> <thin-provisioned>true</thin-provisioned> </backing> <capacity-inKB>1024</capacity-inKB> <shares> <shares>128</shares> <level>custom</level> </shares> </device> </device-change> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Add_Hard_Disk operation. Sample adapter response for the Add_Hard_Disk operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddHardDiskResponse> <Task>task-726</Task> </AddHardDiskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Add_Hard_Disk operation Element Definition Task Required
Task ID of the submitted Task Yes
821
Request and response for the Retrieve_VM_Configuration operation

This operation retrieves the configuration parameters for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine for which the configuration details are to be retrieved
No
No
Yes Yes
The name of the user No If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name Conditional Required if user-name is provided
password
The following figure shows a sample adapter request for the Retrieve_VM_Configuration operation.
822
Sample adapter request for the Retrieve_VM_Configuration operation

<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_VM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>sun1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Retrieve_VM_Configuration operation. Sample adapter response for the Retrieve_VM_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMConfigurationResponse> <returnval> <VirtualMachine>TestDev</VirtualMachine> <propSet> <name>capability</name> <VirtualMachineCapability> <snapshotOperationsSupported>true</snapshotOperationsSupported> <multipleSnapshotsSupported>true</multipleSnapshotsSupported> <snapshotConfigSupported>true</snapshotConfigSupported> <poweredOffSnapshotsSupported>true</poweredOffSnapshotsSupported> <memorySnapshotsSupported>true</memorySnapshotsSupported> <revertToSnapshotSupported>true</revertToSnapshotSupported> <quiescedSnapshotsSupported>true</quiescedSnapshotsSupported> <consolePreferencesSupported>true</consolePreferencesSupported> <cpuFeatureMaskSupported>true</cpuFeatureMaskSupported> <s1AcpiManagementSupported>true</s1AcpiManagementSupported> <settingScreenResolutionSupported>false</settingScreenResolutionSupported> <name>TestDev</name> <guestFullName>Microsoft Windows Server 2003, Standard Edition (32-bit)</guestFullName> <version>vmx-04</version> <uuid>5004090b-99b7-4232-8bf4-1ef1ef420160</uuid> <locationId>564ddc25-1718-9007-8a72-d823c019aff3</locationId> <template>false</template> <guestId>winNetStandardGuest</guestId> <annotation/> <files><vmPathName>[dev15 disk1] TestDev/TestDev.vmx</vmPathName> <snapshotDirectory>[dev15 disk2] TestDev/</snapshotDirectory> <suspendDirectory>[dev15 disk2] TestDev/</suspendDirectory> <logDirectory>[dev15 disk1] TestDev/</logDirectory>
823
</files> <tools> <afterPowerOn>true</afterPowerOn> <afterResume>true</afterResume> <beforeGuestStandby>true</beforeGuestStandby> <beforeGuestShutdown>true</beforeGuestShutdown> </tools> <flags> <disableAcceleration>false</disableAcceleration> <enableLogging>true</enableLogging> <useToe>false</useToe> <runWithDebugInfo>false</runWithDebugInfo> <htSharing>any</htSharing> </flags> <defaultPowerOps> <powerOffType>preset</powerOffType> <suspendType>preset</suspendType> <resetType>preset</resetType> <defaultPowerOffType>hard</defaultPowerOffType> <defaultSuspendType>hard</defaultSuspendType> <defaultResetType>hard</defaultResetType> <standbyAction>checkpoint</standbyAction> </defaultPowerOps> <hardware> <numCPU>1</numCPU> <memoryMB>256</memoryMB> <VirtualIDEController> <key>200</key> <deviceInfo> <label>IDE 0</label> <summary>IDE 0</summary> </deviceInfo> <busNumber>0</busNumber> <device>3000</device> </VirtualIDEController> <VirtualPS2Controller> <key>300</key> <deviceInfo> <label>PS2 Controller </label> <summary>PS2 Controller</summary> </deviceInfo> <busNumber>0</busNumber> <device>600</device> <device>700</device> </VirtualPS2Controller> <VirtualPCIController> <key>100</key> <deviceInfo> <label>PCI Controller </label> <summary>PCI Controller</summary> </deviceInfo> <busNumber>0</busNumber> <device>500</device> </VirtualPCIController> <VirtualSIOController> <key>400</key>
824
<deviceInfo> <label>SIO Controller</label> <summary>SIO Controller</summary> </deviceInfo> <busNumber>0</busNumber> <device>8000</device> </VirtualSIOController> <VirtualKeyboard> <key>600</key> <deviceInfo> <label>Keyboard </label> <summary>Keyboard</summary> </deviceInfo> <controllerkey>300</controllerkey> <unitnumber>0</unitnumber> </VirtualKeyboard> <VirtualPointingDevice> <key>700</key> <deviceInfo> <label>Pointing Device</label> <summary>Pointing device; Device</summary> </deviceInfo> <VirtualPointingDeviceDeviceBackingInfo> <deviceName/> <hostPointingDevice>autodetect</hostPointingDevice> Card </label> <summary>Video Card</summary> </deviceInfo> <controllerkey>100</controllerkey> <unitnumber>0</unitnumber> <videoRamSizeInKB>4096</videoRamSizeInKB> </VirtualMachineVideoCard> <VirtualFloppy> <key>8000</key> <deviceInfo> <label>Floppy Drive 1</label> <summary>Remote /dev/fd0</summary> </deviceInfo> <VirtualFloppyRemoteDeviceBackingInfo> <deviceName>/dev/fd0</deviceName> </VirtualFloppyRemoteDeviceBackingInfo> <connectable> <startConnected>false</startConnected> <allowGuestControl>true</allowGuestControl> <connected>false</connected> </connectable> <controllerkey>400</controllerkey> <unitnumber>0</unitnumber> </VirtualFloppy> <VirtualCdrom> <key>3000</key> <deviceInfo> <label>CD/DVD Drive 1</label> <summary>Remote device</summary> </deviceInfo> <VirtualCdromRemotePassthroughBackingInfo>
825
<deviceName/> <exclusive>false</exclusive> </VirtualCdromRemotePassthroughBackingInfo> <connectable> <startConnected>false</startConnected> <allowGuestControl>true</allowGuestControl> <connected>false</connected> </connectable> <controllerkey>200</controllerkey> </VirtualDisk> <unitnumber>0</unitnumber> </VirtualCdrom> <VirtualPCNet32> <key>4000</key> <deviceInfo> <label>Network Adapter 1</label> <summary>VM Network</summary> </deviceInfo> <VirtualEthernetCardNetworkBackingInfo> <deviceName>VM Network</deviceName> <Network>network-17</Network> </VirtualEthernetCardNetworkBackingInfo> <connectable> <startConnected>true</startConnected> <allowGuestControl>true</allowGuestControl> <connected>true</connected> </connectable> <controllerkey>100</controllerkey> <unitnumber>7</unitnumber> <addressType>assigned</addressType> <macAddress>00:50:56:84:26:8b</macAddress> <wakeOnLanEnabled>true</wakeOnLanEnabled> </VirtualPCNet32> <VirtualLsiLogicController> <key>1000</key> <deviceInfo> <label>SCSI Controller 0</label> <summary>LSI Logic</summary> </deviceInfo> <controllerkey>100</controllerkey> <unitnumber>3</unitnumber> <busNumber>0</busNumber> <device>2000</device> <hotAddRemove>true</hotAddRemove> <sharedBus>noSharing</sharedBus> <scsiCtlrUnitNumber>7</scsiCtlrUnitNumber> Disk 1</label> <summary>0 KB</summary> </deviceInfo> <VirtualDiskFlatVer2BackingInfo> <file-name>[dev15 disk1] TestDev/TestDev-000004.vmdk</file-name> <Datastore>datastore-11</Datastore> <disk-mode>persistent</disk-mode> <split>false</split> <writethrough>false</writethrough>
826
<thinprovisioned>false</thinprovisioned> disk1</name>
<url>/vmfs/volumes/470e81f0-32b2d06a-a25c-0019b9e1 <string>PowerOffVM_Task</string> <string>SuspendVM_Task</string> <string>AcquireMksTicket</string> <string>AnswerVM</string> <string>UpgradeVM_Task</string> <string>UpgradeTools_Task</string> <string>MarkAsVirtualMachine</string> </ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>environmentBrowser</name> <EnvironmentBrowser>envbrowser-2480</EnvironmentBrowser> </propSet> <propSet> <name>guest</name> <GuestInfo> <toolsStatus>toolsNotInstalled</toolsStatus> <guestState>notRunning</guestState> </GuestInfo> </propSet> <propSet> <name>guestHeartbeatStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>layout</name> <VirtualMachineFileLayout> <configFile>TestDev.vmsd</configFile> <configFile>TestDev.vmxf</configFile> <configFile>TestDev.nvram</configFile> <logFile>vmware.log</logFile> <disk> <key>2000</key> <diskFile>[dev15 disk1] TestDev/TestDev-000004.vmdk</diskFile> <diskFile>[dev15 disk1] TestDev/TestDev.vmdk</diskFile> <diskFile>[dev15 disk2] TestDev/TestDev-000002.vmdk</diskFile> </disk> <snapshot> <VirtualMachineSnapshot>snapshot-2693</VirtualMachineSnapshot> disk1] TestDev/TestDev_2.vmdk</snapshotFile> <snapshotFile>[dev15 disk1] TestDev/TestDev.vmdk</snapshotFile> <snapshotFile>[dev15 disk2] TestDev/TestDev-Snapshot18.vmsn</snapshotFile> </snapshot> </VirtualMachineFileLayout> </propSet>
827
<propSet> <name>name</name> <val>TestDev</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference> <Network>network-17</Network> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>group-v3</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission/> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference/> </propSet> <propSet> <name>resourceConfig</name> <ResourceConfigSpec> <VirtualMachine>TestDev</VirtualMachine> <cpuAllocation> <reservation>0</reservation> <expandableReservation>false</expandableReservation> <limit>-1</limit> <shares> <shares>1000</shares> <level>normal</level> </shares> </cpuAllocation> <memoryAllocation> <reservation>0</reservation> <expandableReservation>false</expandableReservation> <limit>-1</limit> <shares> <shares>2560</shares> <level>normal</level> </shares> </memoryAllocation> </propSet> <propSet> <name>resourcePool</name> <ResourcePool>resgroup-2486</ResourcePool> </propSet> <propSet> </ResourceConfigSpec> <name>runtime</name>
828
<VirtualMachineRuntimeInfo> <HostSystem>xyz.bmc.com</HostSystem> <connectionState>connected</connectionState> <powerState>poweredOff</powerState> <toolsInstallerMounted>false</toolsInstallerMounted> <bootTime>2009-06-18T10:23:42.919999Z</bootTime> <suspendInterval>0</suspendInterval> <memoryOverhead>71675904</memoryOverhead> <maxCpuUsage>1862</maxCpuUsage> <maxMemoryUsage>256</maxMemoryUsage> <numMksConnections>0</numMksConnections> </VirtualMachineRuntimeInfo> </propSet> <propSet> <name>snapshot</name> <VirtualMachineSnapshotInfo> <VirtualMachineSnapshot>snapshot-2693</VirtualMachineSnapshot> WS</description> <createTime>2009-05-28T04:51:56.286038-04:00</createTime> <state>poweredOff</state> <quiesced>false</quiesced> <childSnapshotList> <VirtualMachineSnapshot>snapshot-2967</VirtualMachineSnapshot> WS</description> <createTime>2009-06-18T02:59:22.240427-04:00</createTime> <state>poweredOn</state> <quiesced>false</quiesced> </childSnapshotList> </rootSnapshotList> </VirtualMachineSnapshotInfo> </propSet> <propSet> <name>summary</name> <VirtualMachineSummary> <VirtualMachine>TestDev</VirtualMachine> <runtime> <HostSystem>xyz.bmc.com</HostSystem> <connectionState>connected</connectionState> <powerState>poweredOff</powerState> <toolsInstallerMounted>false</toolsInstallerMounted> <bootTime>2009-06-18T10:23:42.919999Z</bootTime> suspendInterval>0</suspendInterval> <memoryOverhead>71675904</memoryOverhead> <maxCpuUsage>1862</maxCpuUsage> <maxMemoryUsage>256</maxMemoryUsage> <numMksConnections>0</numMksConnections> </runtime> <guest> <toolsStatus>toolsNotInstalled</toolsStatus> </guest> <config> <name>TestDev</name> <template>false</template> <vmPathName>[dev15 disk1] TestDev/TestDev.vmx</vmPathName> <memorySizeMB>256</memorySizeMB>
829
<cpuReservation>0</cpuReservation> <memoryReservation>0</memoryReservation> <numCpu>1</numCpu> <numEthernetCards>1</numEthernetCards> <numVirtualDisks>0</numVirtualDisks> <uuid>5004090b-99b7-4232-8bf4-1ef1ef420160</uuid> <guestId>winNetStandardGuest</guestId> <guestFullName>Microsoft Windows Server 2003, Standard Edition (32-bit)</guestFullName> <annotation/> </config> <quickStats> <overallCpuUsage>0</overallCpuUsage> <guestMemoryUsage>0</guestMemoryUsage> <hostMemoryUsage>0</hostMemoryUsage> <guestHeartbeatStatus>gray</guestHeartbeatStatus> </quickStats> <overallStatus>green</overallStatus> </VirtualMachineSummary> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState/> </propSet>
830
</returnval> </RetrieveVMConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_VM_Configuration operation Element VirtualMachineCapability VirtualMachineConfigInfo Datastore Array GuestInfo Definition The information about the operation capabilities of a virtual machine The configuration settings and virtual hardware for a virtual machine The collection of datastore objects in the datacenter that is used by this virtual machine The information about VMware Tools and about the virtual machine from the perspective of VMware Tools Information about the guest operating system is available in Virtual Center. Guest operating system information reflects the last known state of the virtual machine. For machines in the Powered On state, this is current information. For machines in the Powered Off state, this is the last recorded state before the virtual machine was powered off. The guest heartbeat The heartbeat status is classified as: gray: VMware Tools are not installed or not running. red: No heartbeat. Guest operating system may have stopped responding. yellow: Intermittent heartbeat. May be due to guest load. green: Guest operating system is responding normally.
GuestHeartbeatStatus
VirtualMachineFileLayout Network Array ResourceConfigSpec
Detailed information about the files that comprise the virtual machine Collection of network objects in the datacenter that is used by this virtual machine The resource configuration for a virtual machine The shares in this specification are evaluated relative to the resource pool to which it is assigned. This will return null if the product the virtual machine is registered on, does not support resource configuration. The current resource pool that specifies resource allocation for this virtual machine The information about the execution state and history of a virtual machine
ResourcePool VirtualMachineRuntimeInfo
VirtualMachineSnapshotInfo The information about the hierarchy of snapshots in a virtual machine VirtualMachineSummary Basic information about this virtual machine This includes: runtimeInfo guest basic configuration alarms performance information
831
Request and response for the Add_Ethernet_Adapter operation

This operation adds an Ethernet adapter to the specified virtual machine. You can also use this operation to configure the ethernet adapter to use a DV switch for an existing virtual machine. The following table describes the elements for this request. Adapter request elements for the Add_Ethernet_Adapter operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Add_Ethernet_Adapter. Required Yes Yes
soap-url
Specifies the URL for the remote SOAP service running on the VMware No VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
transport
No
parameters virtual-machine
Contains the data types and elements of the operation Contains the name of the virtual machine to which an ethernet adapter is to be added
Yes Yes Yes The device-name element is mandatory if the relevant switch is a standard switch. The dv-portgroup element is
device-change-list the set of Ethernet adapters to be added by the configuration operation Value takes the form:
832
<device-change-list> <device-change> <device type="EthernetAdapterType"> <backing type="VirtualEthernetCardNetworkBackingInfo> <device-name> </device-name> <port> <dv-portgroup></dv-portgroup> <dv-switch></dv-switch> </port> </backing> <connectable> <start-connected> </start-connected> <allow-guest-control> </allow-guest-control> <connected>< /connected>< /connectable> <address-type> </address-type> <mac-address> </mac-address> <wake-on-lan-enabled> </wake-on-lan-enabled> </device> </device-change> </device-change-list>
mandatory if the relevant switch is a DV switch.
For information about the child elements of connectable, see connectable . The valid values for EthernetAdapterType are:
833
VirtualE1000 VirtualPCNet32 VirtualVmxnet The default value for the EthernetAdapterType parameter is VirtualPCNet32. device-name: The name of the device on the host system address-type: MAC address type The valid values for address type are: manual: Statically assigned MAC address assigned: MAC address assigned by the VMware Virtual Center The valid values for the type attribute for the backing element are: VirtualEthernetCardNetworkBackingInfo VirtualEthernetCardDistributedVirtualPortBackingInfo The default value is VirtualEthernetCardNetworkBackingInfo. dv-portgroup: Specifies the name of the DV portgroup with which virtual machine is to be configured Valid value: String dv-switch: Specifies the name of the DV switch with which virtual machine is to be configured Valid value: String The dv-switch element is optional. mac-address: The MAC address assigned to the virtual network adapter. Clients can set this property to any of the permissible address types. The server may override the specified value for Assigned, if the value does not fall within the acceptable ranges or if the value is determined to be a duplicate. wake-on-lan-enabled: Indicates whether the wake-on-LAN feature is enabled on the virtual network adapter. Clients can set this property to selectively enable or disable the wake-on-LAN feature. The valid values for the type attribute for the backing element are: VirtualEthernetCardNetworkBackingInfo VirtualEthernetCardDistributedVirtualPortBackingInfo The default value is VirtualEthernetCardNetworkBackingInfo. dv-portgroup: Specifies the name of the DV portgroup with which virtual machine is to be configured Valid value: String dv-switch: Specifies the name of the DV switch with which virtual machine is to be configured Valid value: String The dv-switch element is optional. mac-address: The MAC address assigned to the virtual network adapter. Clients can set this property to any of the permissible address types. The server may override the specified value for Assigned, if the value does not fall within the acceptable ranges or if the value is determined to be a duplicate. wake-on-lan-enabled: Indicates whether the wake-on-LAN feature is enabled on the virtual network adapter. Clients can set this property to selectively enable or disable the wake-on-LAN feature. host-system user-name Specifies the DNS name of the ESX host of the virtual machine No
The name of the user No If no user name is specified, the request is executed with user specified in the configuration.
834
password
The password corresponding to the specified user name
The following code sample shows a sample adapter request for the Add_Ethernet_Adapter operation. Sample adapter request for the Add_Ethernet_Adapter operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Add_Ethernet_Adapter</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>NewVM</virtual-machine> <spec> <device-change-list> <device-change> <device type="VirtualPCNet32"> <backing> <device-name>VM Network</device-name> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>true</allow-guest-control> <connected>false</connected> </connectable> <address-type>manual</address-type> <mac-address>00:50:56:84:2f:6b</mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Add_Ethernet_Adapter operation for adding a new NIC and configuring it to use a Distributed Virtual Switch (DV Switch) for an existing virtual machine. Sample adapter request for the Add_Ethernet_Adapter operation with DV switch
835
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Add_Ethernet_Adapter</operation-name> <parameters> <virtual-machine>TestDev18</virtual-machine> <host-system>xyz.abc.com</host-system> <spec> <device-change-list> <device-change> <device type="VirtualE1000"> <backing type="VirtualEthernetCardDistributedVirtualPortBackingInfo"> <port> <dv-portgroup>testPG</dv-portgroup> <dv-switch>testDVS</dv-switch> </port> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>false</allow-guest-control> <connected>false</connected> </connectable> <address-type>assigned</address-type> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Add_Ethernet_Adapter operation. Sample adapter response for the Add_Ethernet_Adapter operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddEthernetAdapterResponse> <Task>task-726</Task> </AddEthernetAdapterResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Add_Ethernet_Adapter operation Element Definition Task Task ID of the submitted Task
Request and response for the Add_CD_ROM operation

836
This operation adds a CD ROM device to the specified virtual machine. The following table describes the elements for this request. Note This operation must be executed only when the virtual machine is in Powered Off state.
Adapter request elements for the Add_CD_ROM operation Element operation-type operation-name soap-url Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Add_CD_ROM. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Contains the name of the virtual machine on which the CD ROM is to be added Yes Yes No Required Yes Yes No
837
device-change-list The list of CD ROM devices to be added by the configuration operation Value takes the form:
<device-change-list> <device-change> <device type="VirtualCdrom"> <backing type="BackingInfoType"> <device-name></device-name> <exclusive></exclusive> </backing> </device> </device-change> </device-change-list>
Yes
device type: The VirtualCdrom data object type describes the configuration of a CD-ROM device in a virtual machine Valid value: VirtualCdrom backing: Information about the backing of this virtual device presented in the context of the virtual machine's environment Valid values for BackingInfoType: VirtualCdromRemotePassthroughBackingInfo VirtualCdromRemoteAtapiBackingInfo device-name: The name of the device on the host system Valid values: String values exclusive: The Flag which indicates whether the virtual machine has exclusive CD-ROM device access This element is mandatory. Valid values: true, false
user-name
The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name. Conditional Required if the user-name element is provided
password
The following code sample shows a sample adapter request for the Add_CD_ROM operation. Sample adapter request for the Add_CD_ROM operation
838
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Add_CD_ROM</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <spec> <device-change-list> <device-change> <device type="VirtualCdrom"> <backing type="VirtualCdromRemoteAtapiBackingInfo"> <device-name></device-name> <exclusive>false</exclusive> </backing> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Add_CD_ROM operation. Sample adapter response for the Add_CD_ROM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddCDROMResponse> <Task>task-4146</Task> </AddCDROMResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Add_CD_ROM operation Element Definition Task Task ID of the task
Request and response for the Retrieve_CPU_Configuration operation

This operation retrieves the configuration details of the CPU for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_CPU_Configuration operation
839
Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm.
Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_CPU_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose CPU configuration details are to be retrieved
No
No
Yes Yes
password
The following code sample shows a sample adapter request for the Retrieve_CPU_Configuration operation. Sample adapter request for the Retrieve_CPU_Configuration operation
840
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_CPU_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>sun1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_CPU_Configuration operation. Sample adapter response for the Retrieve_CPU_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveCPUConfigurationResponse> <returnval> <VirtualMachine>TestDev</VirtualMachine> <propSet> <name>config.cpuAllocation</name> <ResourceAllocationInfo> <reservation>256</reservation> <expandableReservation>false</expandableReservation> <limit>256</limit> <shares> <shares>1000</shares> <level>low</level> </shares> </ResourceAllocationInfo> </propSet> <propSet> <name>config.hardware.numCPU</name> <val>2</val> </returnval> </RetrieveCPUConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response element for the Retrieve_CPU_Configuration operation Element Definition
cpuAllocation Resource limits for CPU numCPU Number of virtual CPUs present in this virtual machine
841
Request and response for the Retrieve_Memory_Configuration operation

This operation retrieves the memory for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_Memory_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Memory_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose memory configuration details are to be retrieved
No
No
Yes Yes
password
The following code sample shows a sample adapter request for the Retrieve_Memory_Configuration operation.
842
Sample adapter request for the Retrieve_Memory_Configuration operation

<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_Memory_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>sun1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Memory_Configuration operation. Sample adapter response for the Retrieve_Memory_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveMemoryConfigurationResponse> <returnval> <VirtualMachine>sun1</VirtualMachine> <propSet> <name>config.hardware.memoryMB</name> <val>64</val> </propSet> <propSet> <name>config.memoryAllocation</name> <ResourceAllocationInfo> <reservation>30</reservation> <expandableReservation>false</expandableReservation> <limit>-1</limit> <shares> <shares>128</shares> <level>custom</level> </shares> </ResourceAllocationInfo> </propSet> </returnval> </RetrieveMemoryConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response element for the Retrieve_Memory_Configuration operation Element Definition
memoryAllocation Resource limits for memory
843
memoryMB
Memory size, in MB
Request and response for the Retrieve_Hard_Disk_Configuration operation

This operation retrieves the hard disk parameters for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_Hard_Disk_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Hard_Disk_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose hard disk configuration details are to be retrieved
No
No
Yes Yes
password
844
The following code sample shows a sample adapter request for the Retrieve_Hard_Disk_Configuration operation. Sample adapter request for the Retrieve_Hard_Disk_Configuration operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_Hard_Disk_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>sun1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Hard_Disk_Configuration operation. Sample adapter response for the Retrieve_Hard_Disk_Configuration operation
845
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHardDiskConfigurationResponse> <returnval> <VirtualMachine>TestDev</VirtualMachine> <propSet> <name>config</name> <VirtualMachineConfigInfo> <hardware> <VirtualDisk> <key>2000</key> <deviceInfo> <label>Hard Disk 1</label> <summary>0 KB</summary> </deviceInfo> <VirtualDiskFlatVer2BackingInfo> <fileName>[dev15 disk1] TestDev/TestDev-000004.vmdk</fileName> <Datastore>datastore-11</Datastore> <diskMode>persistent</diskMode> <split>false</split> <writeThrough>false</writeThrough> <thinProvisioned>false</thinProvisioned> </VirtualDiskFlatVer2BackingInfo> <controllerKey>1000</controllerKey> <unitNumber>0</unitNumber> <capacityInKB>0</capacityInKB> <shares> <shares>1000</shares> <level>normal</level> </shares> </VirtualDisk> </hardware> </propSet> </returnval> </RetrieveHardDiskConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Hard_Disk_Configuration operation Element deviceInfo Definition Label and summary information for the device
VirtualDeviceBackingInfo The information about the backing of a device in a virtual machine capacityInKB shares Capacity of the virtual disk Disk shares that are used for resource scheduling
846
Request and response for the Retrieve_CD_ROM_Configuration operation

This operation retrieves the configuration of the CD ROM devices attached to the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_CD_ROM_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_CD_ROM_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose CD ROM information needs to be retrieved The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes No
password
The following code sample shows a sample adapter request for the Retrieve_CD_ROM_Configuration operation.
847
Sample adapter request for the Retrieve_CD_ROM_Configuration operation

<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_CD_ROM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <virtual-machine>Win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_CD_ROM_Configuration operation. Sample adapter response for the Retrieve_CD_ROM_Configuration operation
848
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveCDROMConfigurationResponse> <returnval> <VirtualMachine>TestDev</VirtualMachine> <propSet> <name>config.hardware.device</name> <ArrayOfVirtualDevice> <VirtualCdrom> <key>3000</key> <deviceInfo> <label>CD/DVD Drive 1</label> <summary>Remote device</summary> </deviceInfo> <VirtualCdromRemotePassthroughBackingInfo> <deviceName></deviceName> <exclusive>false</exclusive> </VirtualCdromRemotePassthroughBackingInfo> <connectable> <startConnected>false</startConnected> <allowGuestControl>true</allowGuestControl> <connected>false</connected> </connectable> <controllerkey>200</controllerkey> <unitnumber>0</unitnumber> </VirtualCdrom> <VirtualCdrom> <key>3001</key> <deviceInfo> <label>CD/DVD Drive 2</label> <summary>Remote device /dev/hda</summary> </deviceInfo> <VirtualCdromRemotePassthroughBackingInfo> <deviceName>/dev/hda</deviceName> <exclusive>true</exclusive> </VirtualCdromRemotePassthroughBackingInfo> <connectable> <startConnected>true</startConnected> <allowGuestControl>true</allowGuestControl> <connected>true</connected> </connectable> <controllerkey>200</controllerkey> <unitnumber>1</unitnumber> </VirtualCdrom> </ArrayOfVirtualDevice> </propSet> </returnval> </RetrieveCDROMConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements.
849
Adapter response elements for the Retrieve_CD_ROM_Configuration operation Element deviceInfo Definition Label and summary information for the device
VirtualDeviceBackingInfo The information about the backing of a device in a virtual machine
Request and response for the Retrieve_Ethernet_Adapter_Configuration operation

This operation retrieves the configuration details of the ethernet adapter for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_Ethernet_Adapter_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Ethernet_Adapter_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose ethernet adapter configuration details are to be retrieved
No
No
Yes Yes
The name of the user No If no user name is specified, the request is executed with user specified in the configuration.
850
password
Conditional Required i the user-name element is provided
The following code sample shows a sample adapter request for the Retrieve_Ethernet_Adapter_Configuration operation. Sample adapter request for the Retrieve_Ethernet_Adapter_Configuration operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Retrieve_Ethernet_Adapter_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>sun1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Ethernet_Adapter_Configuration operation.
Sample adapter response for the Retrieve_Ethernet_Adapter_Configuration operation
851
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveEthernetAdapterConfigurationResponse> <returnval> <VirtualMachine>TestDev</VirtualMachine> <propSet> <name>config</name> <VirtualMachineConfigInfo> <hardware> <VirtualPCNet32> <key>4000</key> <deviceInfo> <label>Network Adapter 1</label> <summary>VM Network</summary> </deviceInfo> <VirtualEthernetCardNetworkBackingInfo> <deviceName>VM Network</deviceName> <Network>network-17</Network> </VirtualEthernetCardNetworkBackingInfo> <connectable> <startConnected>true</startConnected> <allowGuestControl>true</allowGuestControl> <connected>true</connected> </connectable> <controllerkey>100</controllerkey> <unitnumber>7</unitnumber> <addressType>assigned</addressType> <macAddress>00:50:56:84:26:8b</macAddress> <wakeOnLanEnabled>true</wakeOnLanEnabled> </VirtualPCNet32> </hardware> </propSet> </returnval> </RetrieveEthernetAdapterConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Ethernet_Adapter_Configuration operation Element deviceInfo Definition Label and summary information for the device
VirtualDeviceBackingInfo The information about the backing of a device in a virtual machine addressType MAC address type Valid values are: Manual: Statically assigned MAC address Assigned: MAC address assigned by Virtual Center
852
macAddress wakeOnLanEnabled
MAC address assigned to the virtual network adapter Indicates whether wake-on-LAN is enabled on the virtual network adapter
Request and response for the Update_CD_ROM_Configuration operation

This operation enables you to attach a previously uploaded ISO file with a CD or DVD drive. The following table describes the elements for this request. Adapter request elements for the Update_CD_ROM_Configuration operation Element operation-type operation-name Definition Defines the type of operation For this operation, the value of operation-type is Configure_Vm. Defines the name of operation For this operation, the value of operation-name is Update_CD_ROM_Configuration. Contains the data types and elements of the operation Contains the name of the virtual machine for which you want to update the CD or DVD configuration details Specifies the display name of the virtual CD ROM device to be updated Required Yes Yes
parameters virtual-machine cdrom
Yes Yes Yes Yes
device-change-list Contains information about the configuration changes for the CD ROM device
<device-change-list> <device-change> <device> <cdrom></cdrom> <backing> <datastore></datastore> <file-name></file-name> </backing> <connectable> <start-connected></start-connected> <allow-guest-control></allow-guest-control> <connected></connected> </connectable> </device> </device-change> </device-change-list>
The datastore element specifies the datastore name where the ISO file is stored. If the file is not located on a datastore, do not specify an empty value. The file-name element specifies the canonical file path for the ISO image. The connectable element is an optional element that specifies the connection properties for the CD-ROM or the DVD device. For more information about the connectable element, see connectable. If you specify the connectable element, it is mandatory to specify values for all the connectable parameters.
853
soap-URL
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-URL is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> elemen is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
user-name
The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
password
Conditional. Required if user-name is provided.
The following code sample shows a sample adapter request for the Update_CD_ROM_Configuration operation. Sample adapter request for the Update_CD_ROM_Configuration operation
854
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_CD_ROM_Configuration</operation-name> <parameters> <virtual-machine>Test1</virtual-machine> <spec> <device-change-list> <device-change> <device> <cdrom>CD/DVD Drive 1</cdrom> <backing> <datastore/> <file-name>/vmimages/tools-isoimages/solaris.iso</file-name> </backing> <connectable> <start-connected>true</start-connected> <allow-guest-control>false</allow-guest-control> <connected>true</connected> </connectable> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_CD_ROM_Configuration operation. Sample adapter response for Update_CD_ROM_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateCDROMConfigurationResponse> <Task>task-981</Task> </UpdateCDROMConfigurationResponse> </vmware-infrastructure-response>
Request and response for the Update_VM_Configuration operation

This operation modifies one or more configuration parameters on a virtual machine. This operation can be used to add or remove a hard disk, CD-ROM drive, or an ethernet adapter from the specified virtual machine. Note Only one hard Disk, CD-ROM, or an ethernet adapter device can be added with one method call of this operation.
The following table describes the elements for this request.
855
Adapter request elements for the Update_VM_Configuration operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Update_VM_Configuration. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine name version guest-id Contains the data types and elements of the operation Yes No Required Yes Yes
soap-url
No
Contains the name of the virtual machine whose configuration details are Yes to be updated The display name of the virtual machine The version string for the virtual machine The short guest operating system identifier For more information about guest-id, see Guest operating system identifiers for VMware Infrastructure. The user-specified description of the virtual machine The configuration of VMware tools running on the guest operating system For more information about the child elements of tools, see tools. Encapsulates the flag settings for a virtual machine For more information about the child elements, see flags. No No No
annotation tools
No No
flags
No
856
console-preferences
Preferences for the legacy console application that affect the way it No behaves during power operations on the virtual machine For more information about the child elements, see console-preferences. Configuration for default power operations For more information about the child elements, see power-op-info. The number of virtual processors in a virtual machine The amount of memory, in MB, for a virtual machine Set of virtual devices being added, removed, or edited by the configuration operation Operation supported: add, remove, edit For more information about the child elements, see: device-change-list for adding devices device-change-list for removing devices device-change-list for updating devices No No No No
power-op-info num-cpus memory-mb device-change-list
cpu-allocation memory-allocation cpu-affinity
The resource limits for CPU For information about child elements, see cpu-allocation. The resource limits for memory For information about child elements, see memory-allocation. List of nodes (processors for CPU) that can be used by the virtual machine If the array is empty when modifying the affinity setting, any existing affinity is removed. List of nodes (NUMA nodes for memory) that can be used by the virtual machine If the array is empty when modifying the affinity setting, any existing affinity is removed. the network traffic shaping specification Traffic shaping is used to configure the network utilization characteristics of a virtual machine. For information about child elements, see network-shaper
No No No
memory-affinity
network-shaper
No
cpu-feature-mask-list Specifies the CPU feature compatibility masks For information about these child elements, see cpu-feature-mask-list. user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No No
password
The following code sample shows a sample adapter request for the Update_VM_Configuration operation to add a hard disk, a CD ROM, and an ethernet adapter. Sample adapter request for the Update_VM_Configuration operation
857
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_VM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <name>winSix</name> <version>vmx-04</version> <guest-id>rhel4Guest</guest-id> <annotation>Test Linux machine</annotation> <tools> <tools-version></tools-version> <after-power-on>true</after-power-on> <after-resume>false</after-resume> <before-guest-standby>true</before-guest-standby> <before-guest-shutdown>true</before-guest-shutdown> <before-guest-reboot>false</before-guest-reboot> </tools> <flags> <disable-acceleration>true</disable-acceleration> <enable-logging>false</enable-logging> <use-toe>false</use-toe> <run-with-debug-info>true</run-with-debug-info> <ht-sharing>any</ht-sharing> </flags> <console-preferences> <power-on-when-opened>true</power-on-when-opened> <enter-full-screen-on-power-on>false</enter-full-screenon-power-on> <close-on-power-off-or-suspend>true</close-on-power-offor-suspend> </console-preferences> <power-op-info> <power-off-type>soft</power-off-type> <suspend-type>soft</suspend-type> <reset-type>soft</reset-type> <default-power-off-type>soft</default-power-off-type> <default-suspend-type>soft</default-suspend-type> <default-reset-type>soft</default-reset-type> <standby-action>checkpoint</standby-action> </power-op-info> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> <device-change-list> <device-change> <operation>add</operation> <device type="VirtualBusLogicController"> <key>0</key> <bus-number>0</bus-number> <device>0</device> <shared-bus>noSharing</shared-bus>
858
</device> </device-change> <device-change> <operation>add</operation> <file-operation>create</file-operation> <device type="VirtualDisk"> <key>0</key> <backing type="VirtualDiskFlatVer2BackingInfo"> <file-name>[dev15 disk2]</file-name> <disk-mode>persistent</disk-mode> <split>true</split> <write-through>true</write-through> <thin-provisioned>false</thin-provisioned> </backing> <controller-key>0</controller-key> <unit-number>-1</unit-number> <capacity-inKB>1024</capacity-inKB> <shares> <shares>1024</shares> <level>low</level> </shares> </device> </device-change> <device-change> <operation>add</operation> <device> <key></key> <device-info> <label>Disk3</label> <summary></summary> </device-info> <controller-key></controller-key> <unit-number></unit-number> </device> </device-change> </device-change-list> <cpu-allocation> <reservation>0</reservation> <limit>-1</limit> <shares> <shares>1862</shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <reservation>0</reservation> <limit>2048</limit> <shares> <shares>2048</shares> <level>custom</level> </shares> </memory-allocation> <cpu-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set>
859
</affinity-set-list> </cpu-affinity> <memory-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </memory-affinity> <network-shaper> <enabled>true</enabled> <peak-bps>10</peak-bps> <average-bps>5</average-bps> <burst-size>8</burst-size> </network-shaper> <cpu-feature-mask-list> <cpu-feature-mask> <operation>add</operation> <info> <level>-2147483648</level> <vendor>amd</vendor> <eax></eax> <ebx></ebx> <ecx></ecx> <edx></edx> </info> </cpu-feature-mask> </cpu-feature-mask-list>
860
The following code sample shows the response for the sample Update_VM_Configuration operation. Sample adapter response for the Update_VM_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ReconfigVM_TaskResponse> <Task>task-727</Task> </ReconfigVM_TaskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Update_VM_Configuration operation Element Definition Task Task ID of the submitted task.
The following code sample shows a sample adapter request for the Update_VM_Configuration operation to remove a hard disk, a CD ROM, and an ethernet adapter. Sample adapter request for the Update_VM_Configuration operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_VM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <name>winSix</name> <version>vmx-04</version> <guest-id>rhel4Guest</guest-id> <annotation>Test Linux machine</annotation> <tools> <tools-version></tools-version> <after-power-on>true</after-power-on> <after-resume>false</after-resume> <before-guest-standby>true</before-guest-standby> <before-guest-shutdown>true</before-guest-shutdown>
861
<before-guest-reboot>false</before-guest-reboot> </tools> <flags> <disable-acceleration>true</disable-acceleration> <enable-logging>false</enable-logging> <use-toe>false</use-toe> <run-with-debug-info>true</run-with-debug-info> <ht-sharing>any</ht-sharing> </flags> <console-preferences> <power-on-when-opened>true</power-on-when-opened> <enter-full-screen-on-power-on>false</enter-full-screenon-power-on> <close-on-power-off-or-suspend>true</close-on-power-offor-suspend> </console-preferences> <power-op-info> <power-off-type>soft</power-off-type> <suspend-type>soft</suspend-type> <reset-type>soft</reset-type> <default-power-off-type>soft</default-power-off-type> <default-suspend-type>soft</default-suspend-type> <default-reset-type>soft</default-reset-type> <standby-action>checkpoint</standby-action> </power-op-info> <num-cpus>1</num-cpus> <memory-mb>32</memory-mb> <device-change-list> <device-change> <operation>remove</operation> <file-operation>destroy</file-operation> <device type="VirtualDisk"> <disk-name>Hard Disk 1</disk-name> </device> </device-change> <device-change> <operation>remove</operation> <device> <cdrom>CD/DVD drive 3</cdrom> </device> </device-change> <device-change> <operation>remove</operation> <device> <ethernet-adapter>Network Adapter 1</ethernet-adapter> </device> </device-change> </device-change-list> <cpu-allocation> <reservation>0</reservation> <limit>-1</limit> <shares> <shares>1862</shares> <level>custom</level> </shares> </cpu-allocation>
862
<memory-allocation> <reservation>0</reservation> <limit>2048</limit> <shares> <shares>2048</shares> <level>custom</level> </shares> </memory-allocation> <cpu-affinity> <affinity-set-list> <affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list> </cpu-affinity> <memory-affinity> <affinity-set-list>
863
<affinity-set>1</affinity-set> <affinity-set>2</affinity-set> </affinity-set-list>
The following code sample shows a sample adapter request for the Update_VM_Configuration operation to update a SCSI controller configuration. Sample adapter request for the Update_VM_Configuration operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_VM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <device-change-list> <device-change> <operation>edit</operation> <device type="VirtualLsiLogicController"> <scsi-controller>SCSI Controller 0</scsi-controller> <bus-number>0</bus-number> <shared-bus>physicalSharing</shared-bus> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Update_VM_Configuration operation to update an ethernet adapter configuration. Sample adapter request for the Update_VM_Configuration operation
864
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_VM_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <device-change-list> <device-change> <operation>edit</operation> <device type="VirtualPCNet32"> <ethernet-adapter>Network Adapter 1</ethernet-adapter> <backing type="VirtualEthernetCardNetworkBackingInfo"> <device-name>DummyNetwork</device-name> </backing> <connectable> <start-connected>true</start-connected> <allow-guest-control>true</allow-guest-control> <connected>true</connected> </connectable> <address-type>assigned</address-type> <mac-address></mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
Request and response for the Update_CPU_Configuration operation

This operation modifies the CPU configuration of the specified virtual machine. This operation can modify the CPU configuration of a virtual machine, even when the virtual machine is in the Power On or Suspended state. The following table describes the elements for this request. Adapter request elements for the Update_CPU_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Update_CPU_Configuration.
865
soap-url
No
transport
No
parameters virtual-machine num-cpus cpu-allocation user-name
Contains the data types and elements of the operation Contains the name of the virtual machine for which you to update the CPU configuration The number of virtual processors in a virtual machine Specifies the resource limits for the CPU For more information about the child elements, see cpu-allocation. The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No No No
password
The following code sample shows a sample adapter request for the Update_CPU_Configuration operation. Sample adapter request for the Update_CPU_Configuration operation
866
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_CPU_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <num-cpus>1</num-cpus> <cpu-allocation> <reservation>256</reservation> <limit>256</limit> <shares> <shares>512</shares> <level>custom</level> </shares> </cpu-allocation> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_CPU_Configuration operation. Sample adapter response for the Update_CPU_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateCPUConfigurationResponse> <Task>task-727</Task> </UpdateCPUConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response element for the Update_CPU_Configuration operation Element Definition Task Task ID of the task.
Request and response for the Update_Memory_Configuration operation

This operation modifies the memory configuration of the specified virtual machine. This operation can modify the memory configuration of a virtual machine, even when the virtual machine is in the Power On or Suspended state. The following table describes the elements for this request. Adapter request elements for the Update_Memory_Configuration operation
867
Element operation-type operation-name
Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Update_Memory_Configuration. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
Required Yes Yes
soap-url
No
transport
No
parameters virtual-machine memory-mb
Contains the data types and elements of the operation Contains the name of the virtual machine whose memory configuration details are to be updated Specifies the memory size of the virtual machine, in MB
Yes Yes No No No
memory-allocation Specifies the resource limits for memory For more information about the child elements, see memory-allocation. user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
password
The following code sample shows a sample adapter request for the Update_Memory_Configuration operation. Sample adapter request for the Update_Memory_Configuration operation
868
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_Memory_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <memory-mb>32</memory-mb> <memory-allocation> <reservation>30</reservation> <limit>2048</limit> <shares> <shares>128</shares> <level>custom</level> </shares> </memory-allocation> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_Memory_Configuration operation. Sample adapter response for the Update_Memory_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateMemoryConfigurationResponse> <Task>task-727</Task> </UpdateMemoryConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Update_Memory_Configuration operation Element Definition Task Task ID of the task.
Request and response for the Update_Ethernet_Adapter_Configuration operation

This operation modifies the configuration of an ethernet adapter on the specified virtual machine.This operation can be modify an ethernet adapter configuration even when the machine is in the Power On and Suspended state. The following table describes the elements for this request. Adapter request elements for the Update_Ethernet_Adapter_Configuration operation
869
Definition Defines the type of the operation. For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation. For this operation, the value of operation-name is Update_Ethernet_Adapter_Configuration. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
Required Yes
operation-name
Yes
soap-url
No
transport
No
Contains the data types and elements of the operation. Contains the name of the virtual machine on which the ethernet adapter configuration is to be updated.
Yes Yes Yes The ethernet adapter name to be updated is a mandatory element. The <device-name> element is valid only for standard switches. The <dv-switch> and <dv-portgroup> elements are valid only for DV switches.
device-change-list the set of Ethernet adapters to be added by the configuration operation Value takes the form:
870
<device-change-list> <device-change> <device type="EthernetAdapterType"> <backing><device-name> </device-name> <port> <dv-portgroup></dv-portgroup> <dv-switch></dv-switch> </backing> <connectable> <start-connected> </start-connected> <allow-guest-control> </allow-guest-control> <connected>< /connected>< /connectable> <address-type> </address-type> <mac-address> </mac-address> <wake-on-lan-enabled> </wake-on-lan-enabled> </device> </device-change> </device-change-list>
The valid values for EthernetAdapterType are:
871
VirtualE1000 VirtualPCNet32 VirtualVmxnet The default value for the EthernetAdapterType parameter is VirtualPCNet32. device-name: The name of the device on the host system address-type: MAC address type The valid values for address type are: manual: Statically assigned MAC address assigned: MAC address assigned by the VMware Virtual Center The valid values for the BackingType attribute for the backing element are: VirtualEthernetCardNetworkBackingInfo VirtualEthernetCardDistributedVirtualPortBackingInfo The default value is VirtualEthernetCardNetworkBackingInfo. dv-portgroup: Specifies the name of the DV portgroup with which virtual machine is to be configured Valid value: String dv-switch: Specifies the name of the DV switch with which virtual machine is to be configured Valid value: String The dv-switch element is optional. mac-address: The MAC address assigned to the virtual network adapter. Clients can set this property to any of the permissible address types. The server may override the specified value for Assigned, if the value does not fall within the acceptable ranges or if the value is determined to be a duplicate. wake-on-lan-enabled: Indicates whether the wake-on-LAN feature is enabled on the virtual network adapter. Clients can set this property to selectively enable or disable the wake-on-LAN feature. start-connected: Flag to specify whether or not to connect the device when the virtual machine starts. allow-guest-control: Flag to allow the guest to control whether the connectable device is connected. connected: Flag indicating the device is currently connected. This flag is valid only while the virtual machine is running. This flag is optional. If you specify the connected element, it is mandatory to specify values for the three connectable parameters start-connected, allow-guest-control, and connected.
host-system user-name
Specifies the DNS name of the ESX host for the virtual machine No The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name. No
password
The following code sample shows a sample adapter request for the Update_Ethernet_Adapter_Configuration
872
operation. Sample adapter request for the Update_Ethernet_Adapter_Configuration operation

<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_Ethernet_Adapter_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>winSix</virtual-machine> <spec> <device-change-list> <device-change> <device type="VirtualPCNet32"> <ethernet-adapter>Network Adapter 1</ethernet-adapter> <backing> <device-name>VM Network</device-name> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>true</allow-guest-control> <connected>false</connected> </connectable> <address-type>manual</address-type> <mac-address>00:50:56:84:2f:6b</mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Update_Ethernet_Adapter_Configuration operation that updates the NIC of an virtual machine from a standard switch to DV switch . Sample adapter request for the Update_Ethernet_Adapter_Configuration operation with DV switch
873
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_Ethernet_Adapter_Configuration</operation-name> <parameters> <virtual-machine>TestDev87</virtual-machine> <host-system>xyz.abc.com</host-system> <spec> <device-change-list> <device-change> <device type="VirtualE1000"> <ethernet-adapter>Network adapter 1</ethernet-adapter> <backing type="VirtualEthernetCardDistributedVirtualPortBackingInfo"> <port> <dv-portgroup>testPG</dv-portgroup> <dv-switch>testDVS</dv-switch> </port> </backing> <connectable> <start-connected>false</start-connected> <allow-guest-control>false</allow-guest-control> <connected>true</connected> </connectable> <address-type>assigned</address-type> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_Ethernet_Adapter_Configuration operation. Sample adapter response for the Update_Ethernet_Adapter_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateEthernetAdapterConfigurationResponse> <Task>task-727</Task> </UpdateEthernetAdapterConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Update_Ethernet_Adapter_Configuration operation Element Definition Task Task ID of the task
874
Request and response for the Update_Hard_Disk_Configuration operation

This operation enables you to increase the size of the hard disk attached to a virtual machine. You can also use this operation to update the disk shares information. The following table describes the elements for the adapter request. Adapter request elements for the Update_Hard_Disk_Configuration operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Configure_VM. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Update_Hard_Disk_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Specifies the name of the virtual machine for which you want to increase the size of the hard disk This element can contain only string values Specifies the name of the hard disk for which you want to increase the size This element can contain only string values Specifies the new capacity for the hard disk, in KB This element can contain only number values
No
No
Yes Yes
disk-name capacity-inKB
Yes Yes
875
shares
Specifies the disk shares which are used for resource scheduling Sample format: <shares> <shares></shares> <level></level> </shares> shares - specifies the number of allocated shares The shares element is used to determine resource allocation, in case of resource contention. This element is required only if the level element is set to custom. The value of this element is a relative measure, based on the settings of the resource pools This element can contain only number values level - specifies the allocation level Level is a simplified view of the shares. Levels map to pre-determined set of numeric values for shares. If the level does not map to pre-defined size, the level element is set to custom. The valid values are: custom - shares specified in the shares element high - 2000 shares low - 500 shares normal - 1000 shares
No
user-name
No
password
The following code sample shows the sample adapter request for the Update_Hard_Disk_Configuration operation. Sample adapter request for the Update_Hard_Disk_Configuration operation
876
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Update_Hard_Disk_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>ClonedVM VIS257</virtual-machine> <spec> <device-change-list> <device-change> <device> <disk-name>Hard Disk 1</disk-name> <capacity-inKB>11264</capacity-inKB> <shares> <shares></shares> <level>normal</level> </shares> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Update_Hard_Disk_Configuration operation. Sample adapter response for the Update_Hard_Disk_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateHardDiskConfigurationResponse> <Task>task-8204</Task> </UpdateHardDiskConfigurationResponse> </vmware-infrastructure-response>
The following table shows the response element for the Update_Hard_Disk_Configuration operation. Adapter response element for the Update_Hard_Disk_Configuration operation Element Definition Task The task ID for the submitted task
Request and response for the Delete_VM operation

This operation deletes the specified virtual machine. The following table describes the elements for this request.
877
Adapter request elements for the Delete_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Delete_VM. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport
Specifies the transport protocol for the message No If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
Contains the data types and elements of the operation Contains the name of the virtual machine to be deleted The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Delete_VM operation. Sample adapter request for the Delete_VM operation
878
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Delete_VM</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>Linux16</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Delete_VM operation. Sample adapter response for the Delete_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <DeleteVMResponse> <Task>task-725</Task> </DeleteVMResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Delete_VM operation Element Definition Task Task ID of the submitted task
Request and response for the Remove_Hard_Disk operation

This operation removes the specified hard disk from a virtual machine. The following table describes the elements for this request. Adapter request elements for the Remove_Hard_Disk operation Element operation-type operation-name Definition Defines the type of the operation Defines the name of operation Required Yes Yes
879
soap-url
No
transport
No
Contains the data types and elements of the operation Contains the name of the virtual machine from which the specified hard disk is to be removed
Yes Yes Yes
device-change-list the set of virtual disks to be removed by the configuration operation Value takes the form:
<device-change-list> <device-change> <device type="VirtualDisk"> <disk-name></disk-name> </device> </device-change> </device-change-list>
disk-name: the name of the hard disk to be removed user-name The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name Conditional Required if the user-name element is provided
password
The following code sample shows a sample adapter request for the Remove_Hard_Disk operation. Sample adapter request for the Remove_Hard_Disk operation
880
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Remove_Hard_Disk</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>TestDev</virtual-machine> <spec> <device-change-list> <device-change> <device type="VirtualDisk"> <disk-name>Hard Disk 1</disk-name> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Hard_Disk operation. Sample adapter response for the Remove_Hard_Disk operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveHardDiskResponse> <Task>task-726</Task> </RemoveHardDiskResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Remove_Hard_Disk operation Element Definition Task Required
Task ID of the submitted Task Yes
Request and response for the Remove_Ethernet_Adapter operation

This operation removes the specified Ethernet adapter from a virtual machine. Note This operation must be performed only when the virtual machine is in the Powered Off state.
The following table describes the elements for this request.

881
Adapter request elements for the Remove_Ethernet_Adapter operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Remove_Ethernet_Adapter. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Contains the name of the virtual machine from which the ethernet adapter is to be removed Yes Yes Yes The name of the ethernet adapter is mandatory. No Required Yes Yes
soap-url
No
device-change-list the set of Ethernet adapters being removed by the configuration operation Value format:
<device-change-list> <device-change> <device> <ethernetadapter></ethernet-adapter> </device> </devicechange> </device-change-list>
ethernet-adapter: the name of the ethernet adapter to be removed user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. No
882
password
The following code sample shows a sample adapter request for the Remove_Ethernet_Adapter operation. Sample adapter request for the Remove_Ethernet_Adapter operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Remove_Ethernet_Adapter</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>Linux16</virtual-machine> <spec> <device-change-list> <device-change> <device> <ethernet-adapter>NetAdpt1</ethernet-adapter> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Ethernet_Adapter operation. Sample adapter response for the Remove_Ethernet_Adapter operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveEthernetAdapterResponse> <Task>task-726</Task> </RemoveEthernetAdapterResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Remove_Ethernet_Adapter operation Element Definition Task Task ID of the submitted Task
883
Request and response for the Remove_CD_ROM operation

This operation removes a CD ROM device from the specified virtual machine. Note This operation must be executed only when the virtual machine is in the Powered Off state.
The following table describes the elements for this request. Adapter request elements for the Remove_CD_ROM operation Element operation-type operation-name soap-url Definition Defines the type of the operation For this operation, the value of operation-type is Configure_Vm. Defines the name of the operation For this operation, the value of operation-name is Remove_CD_ROM. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine Contains the data types and elements of the operation Contains the name of the virtual machine from which the CD ROM must be removed Yes Yes No Required Yes Yes No
884
device-change-list The list of CD ROM devices to be removed by the configuration operation Value takes the form:
<device-change-list> <devicechange> <device> <cdrom></cdrom> </device> </device-change> </device-change-list>
Yes
cdrom : The display name of the virtual CD ROM device to be removed. user-name The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name Conditional Required if the user-name element is provided
password
The following code sample shows a sample adapter request for the Remove_CD_ROM operation. Sample adapter request for the Remove_CD_ROM operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Remove_CD_ROM</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <spec> <device-change-list> <device-change> <device> <cdrom>CD/DVD Drive 3</cdrom> </device> </device-change> </device-change-list> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_CD_ROM operation. Sample adapter response for the Remove_CD_ROM operation
885
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemovelCDROMResponse> <Task>task-4213</Task> </RemovelCDROMResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Remove_CD_ROM operation Element Definition Task Task ID of the task.
Request and response for the Export_VM_As_OVF_Template operation

This operation exports the specified virtual machine as an OVF template and downloads the files that are associated with the virtual machine entity. The following table describes the elements for this request. Adapter request elements for the Export_VM_As_OVF_Template operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VM. Defines the name of the operation For this operation, the value of operation-name is Export_VM_As_OVF_Template. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. Required Yes Yes
soap-url
No
886
transport
No
Contains the data types and elements of the operation Specifies the virtual machine that you want to export as an OVF template Valid value: String
Yes Yes
ovf-download-directory Specifies the directory on the BMC Atrium Orchestrator peer under which the virtual machine OVF descriptor and the other entity files are to be exported Valid value: String cdp Contains the required parameters for generating the OVF descriptor Sample format:
<cdp> <name></name> <description></description> </cdp>
Yes
No
The <name> element specifies the OVF ID to use for the top-level OVF entity. If the OVF ID is not set, the entity's product name is used. If the product name is not available, the VMware Infrastructure entity name is used. Valid value: String The <description> element specifies the contents of the annotation section of the top-level OVF Entity. If the description is not set, any existing annotation on the entity is left unchanged. Valid value: String user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name No
password
The following code sample shows a sample adapter request for the Export_VM_As_OVF_Template operation. Sample adapter request for the Export_VM_As_OVF_Template operation
887
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Export_VM_As_OVF_Template</operation-name> <parameters> <virtual-machine>TestDev3</virtual-machine> <ovf-download-directory>/home/Rominder</ovf-download-directory> <cdp> <name>ExportedVM_OVF</name> <description>TestDescription</description> </cdp> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Export_VM_As_OVF_Template operation. Sample adapter response for the Export_VM_As_OVF_Template operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ExportVmResponse> <ovf-download-directory>/home/test</ovf-download-directory> </ExportVmResponse> </vmware-infrastructure-response>
Request and response for the Import_OVF_Template_As_VM operation

This operation creates a new virtual machine in the resource pool based on the specified OVF descriptor. This operation also uploads the files associated with the virtual machine entity, such as disk files. The following table describes the elements for this request. Adapter request elements for the Import_OVF_Template_As_VM operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VM. Defines the name of the operation For this operation, the value of operation-name is Import_OVF_Template_As_VM. Required Yes
operation-name
Yes
888
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http:// hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
No
parameters datacenter
Contains the data types and elements of the operation Specifies the datacenter where you want to import the virtual machine Valid value: String Specifies the name of the new virtual machine that you want to create by importing the OVF template Valid value: String Specifies the target host on which the new virtual machine will run Valid value: String
Yes Yes
virtual-machine
Yes
host-system
No If the host-system is not specified, you must specify either the parent-virtual-app or the resource-pool element. Yes
datastore
Specifies the datastore on which to create the inventory objects associated with the new virtual machine Valid value: String
parent-virtual-app Specifies the parent vApp under which the virtual machine is to be imported
No If you specify this element, the values in the resource-pool and folder elements are ignored. If you do not specify this element, you must specify either the host-system or resource-pool element.
889
resource-pool
Specifies the resource pool where the virtual machine is to be added Valid value: String
No If the resource-pool element is not specified, you must specify either the host-system or the parent-virtual-app element.
folder
Specifies the folder to which the virtual machine will be No attached Valid value: String If you do not specify this element, the default 'vm' folder is used. Yes No
ovf-descriptor-file Contains the canonical path for the OVF descriptor file Valid value: String user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
password
The following figure shows a sample adapter request for the Import_OVF_Template_As_VM operation. Sample adapter request for the Import_OVF_Template_As_VM operation
<vmware-infrastructure-request> <operation-type>Configure_Vm</operation-type> <operation-name>Import_OVF_Template_As_VM</operation-name> <parameters> <datacenter>datacenter1</datacenter> <virtual-machine>ImportVM</virtual-machine> <host-system>10.118.218.119</host-system> <datastore>Storage1</datastore> <resource-pool>/BMCOne/host/BMC Cluster/Resources/TestRP</resource-pool> <folder>/BMCOne/vm/TestFolder</folder> <ovf-descriptor-file>/home/ExportedVM_OVF/ExportedVM.ovf</ovf-descriptor-file> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Import_OVF_Template_As_VM operation. Sample adapter response for the Import_OVF_Template_As_VM operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ImportVMResponse> <virtual-machine>ImportVM</virtual-machine> </ImportVMResponse> </vmware-infrastructure-response>
890
Adapter requests and responses for Monitor VM operations

The following topics illustrates the adapter requests and responses for the Monitor VM operations.
Request and response for the Retrieve_VM_CPU_Usage operation Request and response for the Retrieve_VM_Disk_Usage operation Request and response for the Retrieve_VM_Memory_Usage operation Request and response for the Retrieve_VM_Network_Usage operation Request and response for the Retrieve_VM_Status operation Request and response for the Retrieve_Task_Status operation Request and response for the Retrieve_VM_Alarm_List operation Request and response for the Delete_VM_Alarm operation
Request and response for the Retrieve_VM_CPU_Usage operation

This operation retrieves the specified VMware Infrastructure CPU usage over the last collection interval. The results returned are for average, minimum, and maximum, and are expressed in 0.01% percentage points (value is from 0 to 10,000). Note Use this operation only when the virtual machine is in the Powered On state.
The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_CPU_Usage operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_CPU_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
891
transport
No
parameters virtual-machine interval-id
Yes
Contains the name of the virtual machine whose CPU usage details are to be Yes retrieved Specifies the real-time sampling period, in seconds, for the performance statistics This element is the same as the refresh rate of the provider which can be verified from the Performance tab in the VMware VirtualCenter client. The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_VM_CPU_Usage operation. Sample adapter request for the Retrieve_VM_CPU_Usage operation
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_CPU_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <query-spec> <interval-id>20</interval-id> </query-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_CPU_Usage operation. Sample adapter response for the Retrieve_VM_CPU_Usage operation
892
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMCPUUsageResponse> < PerfEntityMetric> < VirtualMachine>TestDev</ VirtualMachine > <sampleInfo> <timestamp>2008-04-15T06:54:37Z</timestamp> <interval>20</interval> </sampleInfo> < PerfMetricIntSeries> <id> <counterId>2</counterId> <instance /> <key>2</key> <nameInfo> <label>CPU Usage (Average/Rate)</label> <summary>CPU usage as a percentage over the collected interval</summary> <key>usage</key> </nameInfo> <groupInfo> <label>CPU</label> <summary>CPU</summary> <key>cpu</key> </groupInfo> <unitInfo> <label>Percent</label> <summary>Percentages</summary> <key>percent</key> </unitInfo> <rollupType>average</rollupType> <statsType>rate</statsType> </id> <value>344</value> </ PerfMetricIntSeries > </ PerfEntityMetric > </RetrieveVMCPUUsageResponse> </vmware-infrastructure-response>
The following code sample describes the response elements. Adapter response element for the Retrieve_VM_CPU_Usage operation Element Definition
sampleInfo Information of samples collected in the list. value Metric values corresponding to the samples collected in this list.
Request and response for the Retrieve_VM_Disk_Usage operation

This operation retrieves the sum of the data read and written for all of the disk instances of the host or virtual
893
machine. Results returned are for average, minimum, and maximum, and are expressed in Kbps. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Disk_Usage operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Disk_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine interval-id Contains the data types and elements of the operation Contains the name of the virtual machine whose disk usage details are to be retrieved Specifies the real-time sampling period, in seconds, for the performance statistics This element is the same as the refresh rate of the provider which can be verified from the Performance tab in the VMware VirtualCenter client. The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes Yes
user-name
No
password
894
The following code sample shows a sample adapter request for the Retrieve_VM_Disk_Usage operation. Sample adapter request for the Retrieve_VM_Disk_Usage operation
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_Disk_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>TestDev</virtual-machine> <query-spec> <interval-id>20</interval-id> </query-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_Disk_Usage operation. Sample adapter response for the Retrieve_VM_Disk_Usage operation
895
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMDiskUsageResponse> <PerfEntityMetric> <VirtualMachine>TestDev</VirtualMachine> <sampleInfo> <timestamp>2008-01-01T14:00:59Z</timestamp> <interval>20</interval> </sampleInfo> <PerfMetricIntSeries> <id> <counterId>88</counterId> <instance/> <key>88</key> <nameInfo> <label>Disk Usage(Average/Rate)</label> <summary>Aggregated storage performance statistics. For hosts this can be represented on a per Virtual Machine basis as a stacked graph</summary> <key>usage</key> </nameInfo> <groupInfo> <label>Disk</label> <summary>Disk</summary> <key>disk</key> </groupInfo> <unitInfo> <label>KBps</label> <summary>Kilobytes per second</summary> <key>kiloBytesPerSecond</key> </unitInfo> <rollupType>average</rollupType> <statsType>rate</statsType> </id> <value>0</value> </PerfMetricIntSeries> </PerfEntityMetric> </RetrieveVMDiskUsageResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response element for the Retrieve_VM_Disk_Usage operation Element Definition
sampleInfo Information of samples collected in the list. value Metric values corresponding to the samples collected in the list.
Request and response for the Retrieve_VM_Memory_Usage operation
896
This operation retrieves the current memory in use for the specified virtual machine. Results returned are for average, minimum, and maximum, and are expressed in 0.01% percentage points (value is from 0 to 10,000). The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Memory_Usage operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Memory_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine interval-id Contains the data types and elements of the operation Contains the name of the virtual machine whose memory usage details are to be retrieved Specifies the real-time sampling period, in seconds, for the performance statistics This element is the same as the refresh rate of the provider which can be verified from the Performance tab in the VMware VirtualCenter client. The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes Yes
user-name
No
password
897
The following code sample shows a sample adapter request for the Retrieve_VM_Memory_Usage operation. Sample adapter request for the Retrieve_VM_Memory Usage operation
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_Memory_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <query-spec> <interval-id>20</interval-id> </query-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_Memory_Usage operation. Sample adapter response for the Retrieve_VM_Memory_Usage operation
898
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMMemoryUsageResponse> <PerfEntityMetric> <VirtualMachine>TestDev</VirtualMachine> <sampleInfo> <timestamp>2008-01-01T14:02:59Z</timestamp> <interval>20</interval> </sampleInfo> <PerfMetricIntSeries> <id> <counterId>15</counterId> <instance/> <key>15</key> <nameInfo> <label>Memory Usage (Average/Absolute)</label> <summary>Memory usage as percentage of total configured or available memory</summary> <key>usage</key> </nameInfo> <groupInfo> <label>Memory</label> <summary>Memory</summary> <key>mem</key> </groupInfo> <unitInfo> <label>Percent</label> <summary>Percentages</summary> <key>percent</key> </unitInfo> <rollupType>average</rollupType> <statsType>absolute</statsType> </id> <value>7500</value> </PerfMetricIntSeries> </PerfEntityMetric> </RetrieveVMMemoryUsageResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response element for the Retrieve_VM_Memory_Usage operation Element Definition
Request and response for the Retrieve_VM_Network_Usage operation
899
This operation retrieves the sum of data transmitted and received for all the network interface card instances of the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Network_Usage operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Network_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine interval-id Contains the data types and elements of the operation
No
No
Yes
Contains the name of the virtual machine whose network usage details are to Yes be retrieved Specifies the real-time sampling period, in seconds, for the performance statistics This element is the same as the refresh rate of the provider which can be verified from the Performance tab in the VMware VirtualCenter client. The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name Yes
user-name
No
password
900
The following code sample shows a sample adapter request for the Retrieve_VM_Network_Usage operation. Sample adapter request for the Retrieve_VM_Network_Usage operation
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_Network_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <query-spec> <interval-id>20</interval-id> </query-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_Network_Usage operation. Adapter response for the sample Retrieve_VM_Network_Usage operation
901
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMNetworkUsageResponse> <PerfEntityMetric> <VirtualMachine>TestDev</VirtualMachine> <sampleInfo> <timestamp>2008-01-01T14:04:19Z</timestamp> <interval>20</interval> </sampleInfo> <PerfMetricIntSeries> <id> <counterId>96</counterId> <instance/> <key>96</key> <nameInfo> <label>Network Usage (Average/Rate)</label> <summary>Aggregated network performance statistics. For hosts this can be represented on a per Virtual Machine basis as a stacked graph</summary> <key>usage</key> </nameInfo> <groupInfo> <label>Network</label> <summary>Network</summary> <key>net</key> </groupInfo> <unitInfo> <label>KBps</label> <summary>Kilobytes per second</summary> <key>kiloBytesPerSecond</key> </unitInfo> <rollupType>average</rollupType> <statsType>rate</statsType> </id> <value>0</value> </PerfMetricIntSeries> </PerfEntityMetric> </RetrieveVMNetworkUsageResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_VM_Network_Usage operation Element Definition
Request and response for the Retrieve_VM_Status operation
902
This operation retrieves the operating status of the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Status operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Status. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose status details are to be retrieved The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
Yes Yes No
password
The following code sample shows a sample adapter request for the Retrieve_VM_Status operation. Sample adapter request for the Retrieve_VM_Status operation
903
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_Status</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_Status operation. Sample adapter response for the Retrieve_VM_Status operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMStatusResponse> <returnval> <VirtualMachine>Test</VirtualMachine> <propSet> <name>runtime</name> <VirtualMachineRuntimeInfo> <HostSystem>xyz.bmc.com</HostSystem> <connectionState>connected</connectionState> <powerState>poweredOn</powerState> <toolsInstallerMounted>false</toolsInstallerMounted> <bootTime>2008-01-01T14:00:05.992764Z</bootTime> <suspendInterval>0</suspendInterval> <memoryOverhead>82599936</memoryOverhead> <maxCpuUsage>1862</maxCpuUsage> <maxMemoryUsage>2048</maxMemoryUsage> <numMksConnections>0</numMksConnections> </VirtualMachineRuntimeInfo> </propSet> </returnval> </RetrieveVMStatusResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Retrieve_VM_Status operation Element Definition
VirtualMachineRuntimeInfo The information about the execution state and history of a virtual machine
Request and response for the Retrieve_Task_Status operation
904
This operation retrieves the status, by task ID, of a specific task performed on a virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_Task_Status operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes
operation-name Defines the name of the operation Yes For this operation, the value of operation-name is Retrieve_Task_Status . soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. No
transport
No
parameters spec-set task user-name
Contains the data types and elements of the operation Contains the object set and task ID Task ID whose status has to be determined The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes Yes No
password
The following code sample shows the sample adapter request for the Retrieve_Task_Status operation.
905
Sample adapter request for the Retrieve_Task_Status operation

<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_Task_Status</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <spec-set> <object-set> <task>task-525</task> </object-set> </spec-set> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Task_Status operation. Sample adapter response for the Retrieve_Task_Status operation
906
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveTaskStatusResponse> <returnval> <Task>task-2675</Task> <propSet> <name>info</name> <TaskInfo> <key>task-2675</key> <Task>task-2675</Task> <name>PowerOnVM_Task</name> <descriptionId>VirtualMachine.powerOn</descriptionId> <VirtualMachine>TestDev</VirtualMachine> <entityName>TestDev</entityName> <state>success</state> <cancelled>false</cancelled> <cancelable>false</cancelable> <TaskReasonUser> <userName>bmc</userName> </TaskReasonUser> <queueTime>2009-05-27T08:26:34.234375Z</queueTime> <startTime>2009-05-27T08:26:34.25Z</startTime> <completeTime>2009-05-27T08:26:44.484375Z</completeTime> <eventChainId>71232</eventChainId> </TaskInfo> </propSet> </returnval> </RetrieveTaskStatusResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Task_Status operation Element name entityName state cancelable cancelled progress Definition Name of the operation that created the task Name of the entity to which this operation applies The runtime status of the task Flag to indicate whether the cancel task operation is supported Flag to indicate whether the client requested task cancellation If the task state is running, this element contains a progress measurement, expressed as percentage completed, ranging from 0 to 100
completeTime The time stamp when the task was completed successfully or with a failure error TaskReason If the task state is error, this property contains the fault code Represents the kind of entity responsible for the creation of the task
907
Request and response for the Retrieve_VM_Alarm_List operation

This operation retrieves the list of alarms, including their state, for the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Retrieve_VM_Alarm_List operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_VM_Alarm_List. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine user-name Contains the data types and elements of the operation Contains the name of the virtual machine whose alarm list details are to be retrieved The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes No
password
The following code sample shows a sample adapter request for the Retrieve_VM_Alarm_List operation.
908
Sample adapter request for the Retrieve_VM_Alarm_List operation

<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Retrieve_VM_Alarm_List</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <virtual-machine>win1</virtual-machine> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_VM_Alarm_List operation. Sample adapter response for the Retrieve_VM_Alarm_List operation
909
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVMAlarmListResponse> <returnval> <Alarm>alarm-8</Alarm> <propSet> <name>info</name> <AlarmInfo> <name>VM is powered on</name> <description/> <enabled>true</enabled> <OrAlarmExpression> <StateAlarmExpression> <operator>isEqual</operator> <type>VirtualMachine</type> <statePath>runtime.powerState</statePath> <yellow>suspended</yellow> <red>poweredOff</red> </StateAlarmExpression> </OrAlarmExpression> <GroupAlarmAction> <AlarmTriggeringAction> <SendSNMPAction/> <green2yellow>false</green2yellow> <yellow2red>true</yellow2red> <red2yellow>true</red2yellow> <yellow2green>false</yellow2green> </AlarmTriggeringAction> </GroupAlarmAction> <setting> <toleranceRange>0</toleranceRange> <reportingFrequency>0</reportingFrequency> </setting> <key>alarm-8</key> <Alarm>alarm-8</Alarm> <VirtualMachine>TestDev</VirtualMachine> <lastModifiedTime>2007-11-01T05:07:39Z</lastModifiedTime> <lastModifiedUser>Administrator</lastModifiedUser> <creationEventId>0</creationEventId> </AlarmInfo> </propSet> </returnval> </RetrieveVMAlarmListResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Retrieve_VM_Alarm_List operation Element Definition
910
Alarm Info Detailed information about the alarm
Request and response for the Delete_VM_Alarm operation

This operation removes the alarm from the list of alarms affecting the specified virtual machine. The following table describes the elements for this request. Adapter request elements for the Delete_VM_Alarm operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Monitor_Vm. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Delete_VM_Alarm. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-machine name user-name Contains the data types and elements of the operation Contains the name of the virtual machine from which an alarm is to be removed The name of the alarm to be deleted The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
Yes Yes Yes No
password
911
The following code sample shows a sample adapter request for the Delete_VM_Alarm operation. Sample adapter request for the Delete_VM_Alarm operation
<vmware-infrastructure-request> <operation-type>Monitor_Vm</operation-type> <operation-name>Delete_VM_Alarm</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-machine>win1</virtual-machine> <name>New Alarm</name> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Delete_VM_Alarm operation. Sample adapter response for the Delete_VM_Alarm operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <DeleteVMAlarmResponse/> </vmware-infrastructure-response>
Adapter requests and responses for Host operations

The following topics illustrates the adapter requests and responses for the Host operations.
Request and response for the Create_Host operation Request and response for the Add_Host_To_Cluster operation Request and response for the Add_Virtual_Switch operation Request and response for the Add_Virtual_NIC operation Request and response for the Add_Port_Group operation Request and response for the Add_NAS_Datastore operation Request and response for the Add_Vmfs_Datastore operation Request and response for the Add_Internet_Scsi_Send_Targets operation Request and response for the Move_Host_To_Cluster operation Request and response for the Retrieve_Host_Configuration operation Request and response for the Retrieve_Host_DVS_Configuration operation Request and response for the Retrieve_Host_Network_Configuration operation Request and response for the Retrieve_Host_Datastore_Configuration operation Request and response for the Retrieve_Virtual_Switch_Configuration operation Request and response for the Retrieve_Virtual_NIC_Configuration operation Request and response for the Retrieve_Port_Group_Configuration operation Request and response for the Retrieve_Available_Disks_For_Vmfs operation Request and response for the Retrieve_Host_CPU_Usage operation Request and response for the Retrieve_Host_Memory_Usage operation
912
Request and response for the Retrieve_ESX_Hosts operation Request and response for the Retrieve_Host_Scsi_Topology operation Request and response for the Rescan_Hba operation Request and response for the Rescan_All_Hba operation Request and response for the Update_Host_Network_Configuration operation Request and response for the Extend_Vmfs_Datastore operation Request and response for the Update_Software_Internet_Scsi_Enabled operation Request and response for the Update_Internet_Scsi_Name operation Request and response for the Remove_Host_From_Cluster operation Request and response for the Remove_Virtual_Switch operation Request and response for the Remove_Virtual_NIC operation Request and response for the Remove_Port_Group operation Request and response for the Remove_Datastore operation Request and response for the Enter_Maintenance_Mode operation Request and response for the Exit_Maintenance_Mode operation
Request and response for the Create_Host operation

This operation adds a standalone ESX server to the VMware Virtual Center. You can specify an IP address or a string for creating a host. By default, you can use this operation to add only an SSL-verified host to the datacenter. However, you can override this default setting and add non-SSL verified hosts to the datacenter.
To add a non-SSL verified host
1. Log on to the Virtual Center client. 2. Navigate to Administration=> VirtualCenter Management Server Configuration=> SSL Settings. 3. Un-check check host certificates.
The following table describes the elements for this request. Adapter request elements for the Create_Host operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Create_Host. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
913
transport
No
parameters folder datacenter spec add-connected
Contains the data types and elements of the operation Specifies the folder in which the host must be created If this element is not specified, the host is created in the default host folder. Name of the datacenter where host is to be created Specifies the parameters needed to add a single host For information about the child elements, see spec Flag to specify whether the host connects as soon as it is added The creation operation fails if a connection attempt is made and fails. Valid values: true, false The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes No Yes Yes Yes
user-name
No
password
Note The user-name and password attributes are verified only if add-connected is set to true.
The following figure shows a sample adapter request for the Create_Host operation. Sample adapter request for the Create_Host operation
914
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Create_Host</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <folder>TestHostFolder</folder> <datacenter>BMC</datacenter> <spec> <force>false</force> <host-name>abc.bmc.com</host-name> <password></password> <port></port> <user-name>root</user-name> <vim-account-name></vim-account-name> <vim-account-password></vim-account-password> <folder>vm</folder> </spec> <add-connected>false</add-connected> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Create_Host operation. Sample adapter response for the Create_Host operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateHostResponse> <Task>task-731</Task> </CreateHostResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Create_Host operation Element Definition Task Task ID of the task
Request and response for the Add_Host_To_Cluster operation

This operation adds an ESX server to the specified cluster on the VMware Virtual Center. The specified host name must be a DNS resolvable name. For example, host1.domain.com. By default, you can use this operation to add only an SSL-verified host to the datacenter. However, you can override this default setting and add non-SSL verified hosts to the datacenter.
915
To add a non-SSL verified host
1. Log on to the Virtual Center client. 2. Navigate to Administration=> VirtualCenter Management Server Configuration=> SSL Settings. 3. Un-check check host certificates. The following table describes the elements for this request. Adapter request elements for the Add_Host_To_Cluster operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Host. Defines the name of the operation For this operation, the value of operation-name is Add_Host_To_Cluster. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation Yes Yes Yes Yes No Required Yes Yes
soap-url
No
cluster-compute-resource The cluster compute resource to which the host must be added datacenter spec The name of the datacenter where the host is to be created Specifies the parameters needed to add a single host The host-name, user-name, and password elements are mandatory. Sample format: For information about the child elements, see spec.
916
as-connected
Flag to specify whether or not the host should be connected immediately after it is added If the host is to be connected immediately after it is added, but the connection fails, an exception error occurs. Valid values: true, false. The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes
user-name
No
password
The following figure shows a sample adapter request for the Add_Host_To_Cluster operation. Sample adapter request for the Add_Host_To_Cluster operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Host_To_Cluster</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <cluster-compute-resource>TestCluster</cluster-compute-resource> <as-connected>false</as-connected> <datacenter>BMC_DEV</datacenter> <spec> <force>false</force> <host-name>xyz.bmc.com</host-name> <password></password> <port></port> <user-name>root</user-name> <vim-account-name></vim-account-name> <vim-account-password></vim-account-password> <folder>vm</folder> </spec> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Add_Host_To_Cluster operation. Sample adapter response for the Add_Host_To_Cluster operation
917
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddHostToClusterResponse> <Task>task-733</Task> </AddHostToClusterResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Add_Host_To_Cluster operation Element Definition Task Task ID of the task
Request and response for the Add_Virtual_Switch operation

This operation updates the configuration of a host network to add a virtual switch. The following table describes the elements for this request. Adapter request elements for the Add_Virtual_Switch operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Add_Virtual_Switch. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
918
transport
No
parameters host-system
Contains the data types and elements of the operation DNS name of the host on the network to which the virtual switch is to be added Valid values: dns name Contains the list of virtual switches to be added on the host Operation supported: add For more information, see XML sample for vswitch-list. The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes
vswitch-list
Yes
user-name
No
password
The following figure shows a sample adapter request for the Add_Virtual_Switch operation. Sample adapter request for the Add_Virtual_Switch operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Virtual_Switch</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vswitch-list> <vswitch> <name>vSwitch4</name> <spec> <num-ports>56</num-ports> <policy> <security> <allow-promiscuous>true</allow-promiscuous>
919
<mac-changes>false</mac-changes> <forged-transmits>false</forged-transmits> </security> <nic-teaming> <policy>failover_explicit</policy> <reverse-policy>true</reverse-policy> <notify-switches>false</notify-switches> <rolling-order>true</rolling-order> <failure-criteria> <check-speed>exact</check-speed> <speed>32</speed> <check-duplex>true</check-duplex> <full-duplex>true</full-duplex> <check-error-percent>true</check-error-percent> or more repetitions:--> <active-nic-list> <active-nic></active-nic> <active-nic></active-nic> </active-nic-list>  <standby-nic-list> <standby-nic></standby-nic> <standby-nic></standby-nic> </standby-nic-list> </nic-order> </nic-teaming> <offload-policy> <csum-offload>false</csum-offload> <tcp-segmentation>false</tcp-segmentation> <zero-copy-xmit>false</zero-copy-xmit> </offload-policy> <shaping-policy> <enabled>true</enabled> <average-bandwidth>102400</average-bandwidth> <peak-bandwidth>102400</peak-bandwidth> <burst-size>102400</burst-size> </shaping-policy> </policy> </spec> </vswitch> </vswitch-list>
920
</config> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Add_Virtual_Switch operation. Sample adapter response for the Add_Virtual_Switch operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddVirtualSwitchResponse> <returnval/> </AddVirtualSwitchResponse> </vmware-infrastructure-response>
Request and response for the Add_Virtual_NIC operation

This operation updates the configuration of a host network to add a virtual NIC.
The following table describes the elements for this request. Adapter request elements for the Add_Virtual_NIC operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required No Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Add_Virtual_NIC. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
921
transport
No
parameters host-system vnic-list
Contains the data types and elements of the operation DNS name of the host on the network to which the virtual NIC is to be added Valid values: dns name Contains the list of virtual switches network adapters configured for use by the host operating system network adapter For more information, see XML Sample for vnic-list. The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Add_Virtual_NIC operation. Sample adapter request for the Add_Virtual_NIC operation
922
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Virtual_NIC</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vnic-list> <vnic> <portgroup>Virtual Machine Network 2</portgroup> <spec> <ip> <dhcp>false</dhcp> <ip-address>127.21.10.10</ip-address> <subnet-mask>255.255.255.0</subnet-mask> </ip> <mac></mac> </spec> </vnic> </vnic-list> </config> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Add_Virtual_NIC operation. Sample adapter response for the Add_Virtual_NIC operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddVirtualNICResponse> <returnval> <vnicDevice>portgroup7</vnicDevice> </returnval> </AddVirtualNICResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Add_Virtual_NIC operation Element Definition
vnicDevice The Virtual NIC name added to the Port group
923
Request and response for the Add_Port_Group operation

This operation updates the configuration of a host network to add a port group. The following table describes the elements for this request. Adapter request elements for the Add_Port_Group operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Add_Port_Group. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation DNS name of the host on the network to which the port group is to be added Valid values: dns name Contains the list of port groups to be added on the host For more information, see portgroup-list.
No
No
Yes Yes
portgroup-list
Yes The name of the port group and the name of the switch on which the port group is to be located are mandatory.
924
user-name
The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name Conditional Required if the user-name element is provided
password
The following figure shows a sample adapter request for the Add_Port_Group operation. Sample adapter request for the Add_Port_Group operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Port_Group</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <portgroup-list> <portgroup> <spec> <name>VM Network 2</name> <vlan-id>0</vlan-id> <vswitch-name>vSwitch4</vswitch-name> <policy> <security> <allow-promiscuous></allow-promiscuous> <mac-changes></mac-changes> <forged-transmits></forged-transmits> </security> <nic-teaming> <policy></policy> <reverse-policy></reverse-policy> <notify-switches></notify-switches> <rolling-order></rolling-order> <failure-criteria> <check-speed></check-speed> <speed></speed> <check-duplex></check-duplex> <full-duplex></full-duplex> <check-error-percent></check-error-percent>
The following figure shows the response for the sample Add_Port_Group operation. Sample adapter response for the Add_Port_Group operation
925
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddPortGroupResponse> <returnval/> </AddPortGroupResponse> </vmware-infrastructure-response>
Request and response for the Add_NAS_Datastore operation

This operation enables you to create a new storage datastore attached to the network. The following table describes the elements for the adapter request. Adapter request elements for the Add_NAS_Datastore operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Add_NAS_Datastore. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system remote-host Contains the data types and elements of the operation Specifies the DNS name of the host on which you want to add the datastore This element can contain only String values Specifies the host running the Network File System (NFS) server
No
Yes Yes Yes
926
remote-path local-path access-node
Specifies the remote path for the NFS mount point Specifies the name for the new datastore Specifies the access node for the mount point Valid values are readOnly and readWrite. If this element is set to readOnly, the virtual machine has read-only access to the datastore. If this element is set to readWrite, the virtual machine has read and write access to the datastore. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes Yes
user-name
No
password
The following figure shows a sample adapter request for the Add_NAS_Datastore operation. Sample adapter request for the Add_NAS_Datastore operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_NAS_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <spec> <remote-host>10.251.1.69</remote-host> <remote-path>/vol/test1/bmc1</remote-path> <local-path>NetAppNASStorage1</local-path> <access-mode>readWrite</access-mode> </spec> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample adapter request. Sample adapter response for the Add_NAS_Datastore operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddNASDatastoreResponse> <Datastore>datastore-6114</Datastore> </AddNASDatastoreResponse> </vmware-infrastructure-response>
927
The following table describes the response element for the Add_NAS_Datastore operation. Adapter response element for the Add_NAS_Datastore operation Element Description
Datastore Specifies the newly created datastore
Request and response for the Add_Vmfs_Datastore operation

This operation enables you to add a new VMFS datastore to an ESX server. The following table describes the elements for the adapter request. Adapter request elements for the Add_Vmfs_Datastore operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Add_Vmfs_Datastore. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name for the host for which you want to add the datastore This element can contain only string values.
No
Yes Yes
928
disk-name
Specifies the name of the VMware Virtual Machine File System (Vmfs) storage
Conditional Required if the_serial-number_ is not provided Conditional Required if the_disk-name_ is not provided
serial-number
Specifies the serial number for the Vmfs storage Note This element is only valid for NetApp Storage.
datastore-name Specifies the name of the datastore that you want to add user-name The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes No
password
The following figure shows the sample adapter request for the Add_Vmfs_Datastore operation with the serial-number element. Sample adapter request for the Add_Vmfs_Datastore operation with the serial-number element
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Vmfs_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <serial-number>nBOOIJWk5G7b</serial-number> <datastore-name>SAN2</datastore-name> </parameters> </vmware-infrastructure-request>
The following figure shows the sample adapter request for the Add_Vmfs_Datastore operation with the disk-name element. Sample adapter request for the Add_Vmfs_Datastore operation with the disk-name element
929
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Vmfs_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <disk-name>vmhba32:1:0</disk-name> <datastore-name>SAN2</datastore-name> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Add_Vmfs_Datastore operation. Sample adapter response for the Add_Vmfs_Datastore operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddVmfsDatastoreResponse> <Datastore>datastore-6141</Datastore> </AddVmfsDatastoreResponse> </vmware-infrastructure-response>
The following table shows the response elements for the Add_Vmfs_Datastore operation. Adapter response elements for the Add_Vmfs_Datastore operation Element Definition
Datastore The newly created datastore
Request and response for the Add_Internet_Scsi_Send_Targets operation

This operation allows you to add Send Target entries to the host bus adapter (HBA) discovery list. The following table describes the elements for the adapter request. Adapter request elements for the Add_Internet_Scsi_Send_Targets operation Element operation-type operation-name Definition Defines the type of operation For this operation, the value of operation-type is Host. Defines the name of operation For this operation, the value of operation-name is Add_Internet_Scsi_Send_Targets. Required Yes Yes
930
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
No
Contains the data types and elements of the operation Specifies the DNS name of the host for which you want to add the send targets to the bus adapter discovery list This element can contain only string values.
Yes Yes
iScsi-hba-device Specifies the device of the Internet SCSI HBA adapter This element can contain only string values. targets-list Specifies an array of Internet SCSI send targets Sample format:
<targets-list> <targets> <address>10.118.219.17</address> <port>3260</port> </targets> ............... </targets-list>
Yes Yes
address: String value specifying the IP address or hostname of the storage device port:Specifies the TCP port of the storage device The default value for the port element is 3260 and this element can contain only integer values. user-name The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name No
password
931
The following code sample shows the sample adapter request for the Add_Internet_Scsi_Send_Targets operation. Sample adapter request for the Add_Internet_Scsi_Send_Targets operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Add_Internet_Scsi_Send_Targets</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>abc.bmc.com</host-system> <iScsi-hba-device>vmhba40</iScsi-hba-device> <targets-list> <targets> <address>10.118.249.20</address> <port>3260</port> </targets> </targets-list> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Add_Internet_Scsi_Send_Targets operation. Sample adapter response for the Add_Internet_Scsi_Send_Targets operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <AddInternetScsiSendTargetsResponse> </AddInternetScsiSendTargetsResponse> </vmware-infrastructure-response>
Request and response for the Move_Host_To_Cluster operation

This operation moves the specified host into a specified cluster. The following table describes the elements for this request. Note The host must be part of the same datacenter, and if the host is part of a cluster, the host must be in the maintenance mode.
Adapter request elements for the Move_Host_To_Cluster operation Element Definition Required
932
operation-type operation-name
Defines the type of the operation For this operation, the value of operation-type is Host. Defines the name of the operation For this operation, the value of operation-name is Move_Host_To_Cluster. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
Yes Yes
soap-url
No
transport
No
parameters
Yes Yes Yes No
cluster-compute-resource The cluster compute resource to which the host needs to move host-system user-name DNS name of the host to move into the cluster Valid value: DNS name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
password
The following code sample shows a sample adapter request for the Move_Host_To_Cluster operation. Sample adapter request for the Move_Host_To_Cluster operation
933
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Move_Host_To_Cluster</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <cluster-compute-resource>TestCluster</cluster-compute-resource> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Move_Host_To_Cluster operation. Sample adapter response for the Move_Host_To_Cluster operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <MoveHostToClusterResponse> <Task>task-732</Task> </MoveHostToClusterResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Move_Host_To_Cluster operation Element Definition Task Task ID of the task
Request and response for the Retrieve_Host_Configuration operation

This operation retrieves the configuration details details of a host machine, including details about allocated CPU, used CPU, memory, IP address, MAC address, and port groups. The following table describes the elements for this request. Adapter request elements for the Retrieve_Host_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Host_Configuration.
934
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message.If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. The valid values are https-rpc and http-rpc. Note If the value of the <transport> elemen is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No.
Contains the data types and elements of the operation DNS name of the host machine whose configuration details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Host_Configuration operation. Sample adapter request for the Retrieve_Host_Configuration operation
935
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com </host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_Configuration operation. Sample adapter response for the Retrieve_Host_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostConfigurationResponse> <returnval> <HostSystem>xyz.bmc.com</HostSystem> <propSet> <name>config.network.consoleVnic</name> <ArrayOfHostVirtualNic> <HostVirtualNic> <device>vswif0</device> <key>key-vim.host.VirtualNic-vswif0</key> <portgroup>Service Console</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>172.21.124.115</ipAddress> <subnetMask>255.255.255.0</subnetMask> </ip> <mac>00:50:56:44:9f:1e</mac> </spec> <port>key-vim.host.PortGroup.Port-16777220</port> </HostVirtualNic> </ArrayOfHostVirtualNic> </propSet> <propSet> <name>summary</name> <HostListSummary> <HostSystem>xyz.bmc.com</HostSystem> <hardware> <vendor>Dell Inc.</vendor> <model>PowerEdge 1950</model> <uuid>44454c4c-3200-1035-8044-b2c04f314431</uuid> <memorySize>34359377920</memorySize>
936
<cpuModel>Intel(R) Xeon(R) CPU L5320 @ 1.86GHz</cpuModel> <cpuMhz>1862</cpuMhz> <numCpuPkgs>2</numCpuPkgs> <numCpuCores>8</numCpuCores> <numCpuThreads>8</numCpuThreads> <numNics>2</numNics> <numHBAs>1</numHBAs> </hardware> <runtime> <connectionState>connected</connectionState> <inMaintenanceMode>false</inMaintenanceMode> <bootTime>2009-09-03T16:37:20.2061Z</bootTime> </runtime> <config> <name>xyz.bmc.com</name> <port>443</port> <product> <name>VMware ESX Server</name> <fullName>VMware ESX Server 3.5.0 build-110268</fullName> <vendor>VMware, Inc.</vendor> <version>3.5.0</version> <build>110268</build> <localeVersion>INTL</localeVersion> <localeBuild>000</localeBuild> <osType>vmnix-x86</osType> <productLineId>esx</productLineId> <apiType>HostAgent</apiType> <apiVersion>2.5u2</apiVersion> </product> <vmotionEnabled>false</vmotionEnabled> </config> <quickStats> <overallCpuUsage>1417</overallCpuUsage> <overallMemoryUsage>10784</overallMemoryUsage> <distributedCpuFairness>2295</distributedCpuFairness> <distributedMemoryFairness>676</distributedMemoryFairness> </quickStats> <overallStatus>green</overallStatus> <rebootRequired>false</rebootRequired> </HostListSummary> </propSet>
937
</returnval> </RetrieveHostConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements that describes the availability of the Host Resources. Adapter response elements for the Retrieve_Host_Configuration operation Element HostSystem HostVirtualNic Definition Name of the ESX host configured on the VMware VirtualCenter Describes a virtual network adapter representing an adapter that connects to a virtual switch It contains information such as the IP and the MAC address of the virtual network adapter. Contains the basic host statistics including basic configuration, hardware, and runtime information. Basic host statistics. This element also contains the rebootRequired flag that indicates whether the host requires a reboot due to a configuration change Allocated memory size, in bytes Allocated CPU, in MHz Overall CPU usage, in MHz
HostListSummary
memorySize cpuMhz overallCpuUsage
overallMemoryUsage Overall memory usage, in MB
Request and response for the Retrieve_Host_DVS_Configuration operation

This operation enables you to retrieve the DV Switch and DV Portgroup configured on the specified ESX host. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Host_DVS_Configuration operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Host_DVS_Configuration.
938
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
No
Contains the data types and elements of the operation Specifies the DNS name of the ESX server for which you want to retrieve the DV switch and DV portgroup This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows the sample adapter request for the Retrieve_Host_DVS_Configuration operation. Sample adapter request for the Retrieve_Host_DVS_Configuration operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_DVS_Configuration</operation-name> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_DVS_Configuration operation. Sample adapter response for the Retrieve_Host_DVS_Configuration operation
939
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostDVSConfigurationResponse> <returnval> <distributedVirtualPortgroup> <switchName>dvSw-C3-New</switchName> <switchUuid>66 6f 19 50 01 db c0 26-1c af 82 6b cd f7 f3 9b</switchUuid> <portgroupName>dvSw-C3-New-DVUplinks-20245</portgroupName> <portgroupKey>dvportgroup-20246</portgroupKey> <portgroupType>earlyBinding</portgroupType> <uplinkPortgroup>true</uplinkPortgroup> <portgroup type="DistributedVirtualPortgroup">dvportgroup-20246</portgroup> </distributedVirtualPortgroup> <distributedVirtualPortgroup> <switchName>dvSw-C3-New</switchName> <switchUuid>66 6f 19 50 01 db c0 26-1c af 82 6b cd f7 f3 9b</switchUuid> <portgroupName>dvPortGroup2</portgroupName> <portgroupKey>dvportgroup-20819</portgroupKey> <portgroupType>earlyBinding</portgroupType> <uplinkPortgroup>false</uplinkPortgroup> <portgroup type="DistributedVirtualPortgroup">dvportgroup-20819</portgroup> </distributedVirtualPortgroup> <distributedVirtualPortgroup> <switchName>dvSwitch2</switchName> <switchUuid>7f e9 19 50 a0 b7 87 4f-c6 47 bb a7 62 66 ba f5</switchUuid> <portgroupName>dvSwitch2-DVUplinks-20822</portgroupName> <portgroupKey>dvportgroup-20823</portgroupKey> <portgroupType>earlyBinding</portgroupType> <uplinkPortgroup>true</uplinkPortgroup> <portgroup type="DistributedVirtualPortgroup">dvportgroup-20823</portgroup> </distributedVirtualPortgroup> <distributedVirtualPortgroup> <switchName>dvSwitch2</switchName> <switchUuid>7f e9 19 50 a0 b7 87 4f-c6 47 bb a7 62 66 ba f5</switchUuid> <portgroupName>dvPortGroup3</portgroupName> <portgroupKey>dvportgroup-20824</portgroupKey> <portgroupType>earlyBinding</portgroupType> <uplinkPortgroup>false</uplinkPortgroup> <portgroup type="DistributedVirtualPortgroup">dvportgroup-20824</portgroup> </distributedVirtualPortgroup> <distributedVirtualSwitch> <switchName>dvSw-C3-New</switchName> <switchUuid>66 6f 19 50 01 db c0 26-1c af 82 6b cd f7 f3 9b</switchUuid> <distributedVirtualSwitch type="VmwareDistributedVirtualSwitch">dvs-20245</distributedVirtualSwitch> </distributedVirtualSwitch> <distributedVirtualSwitch> <switchName>dvSwitch2</switchName> <switchUuid>7f e9 19 50 a0 b7 87 4f-c6 47 bb a7 62 66 ba f5</switchUuid> <distributedVirtualSwitch type="VmwareDistributedVirtualSwitch">dvs-20822</distributedVirtualSwitch> </distributedVirtualSwitch>
940
</returnval> </ RetrieveHostDVSConfigurationResponse> </vmware-infrastructure-response>
Request and response for the Retrieve_Host_Network_Configuration operation

This operation retrieves the details of the host network including details about the virtual switch, virtual NIC, and the port group. The following table describes the elements for this request. Adapter request elements for the Retrieve_Host_Network_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Host_Network_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation DNS name of the host for which the network configuration details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request is executed with the user specified in the configuration.
No
No
Yes Yes
user-name
No
941
password
The following code sample shows a sample adapter request for the Retrieve_Host_Network_Configuration operation. Sample adapter request for the Retrieve_Host_Network_Configuration operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_Network_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_Network_Configuration operation. Sample adapter response for the Retrieve_Host_Network_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostNetworkConfigurationResponse> <returnval> <HostNetworkSystem>networkSystem-75</HostNetworkSystem> <propSet> <name>networkInfo</name> <HostNetworkInfo> <vswitch> <name>vSwitch0</name> <key>key-vim.host.VirtualSwitch-vSwitch0</key> <numPorts>32</numPorts> <numPortsAvailable>28</numPortsAvailable> <portgroup>key-vim.host.PortGroup-VM Network</portgroup> <portgroup>key-vim.host.PortGroup-Service Console</portgroup> <pnic>key-vim.host.PhysicalNic-vmnic0</pnic> <spec> <numPorts>32</numPorts> <HostVirtualSwitchBondBridge> <nicDevice>vmnic0</nicDevice> <beacon> <interval>1</interval>
942
</beacon> </HostVirtualSwitchBondBridge> <policy> <security> <allowPromiscuous>false</allowPromiscuous> <macChanges>true</macChanges> <forgedTransmits>true</forgedTransmits> </security> <nicTeaming> <policy>loadbalance_srcid</policy> <reversePolicy>true</reversePolicy> <notifySwitches>true</notifySwitches> <rollingOrder>false</rollingOrder> <failureCriteria> <checkSpeed>minimum</checkSpeed> <speed>10</speed> <checkDuplex>false</checkDuplex> <fullDuplex>false</fullDuplex> <checkErrorPercent>false</checkErrorPercent> <percentage>0</percentage> <checkBeacon>false</checkBeacon> </failureCriteria> <nicOrder> <activeNic>vmnic0</activeNic> </nicOrder> </nicTeaming> <offloadPolicy> <csumOffload>true</csumOffload> <tcpSegmentation>false</tcpSegmentation> <zeroCopyXmit>true</zeroCopyXmit> </offloadPolicy> <shapingPolicy> <enabled>false</enabled> </shapingPolicy> </policy> </spec> </vswitch> <portgroup> <key>key-vim.host.PortGroup-VM Network</key> <vswitch>key-vim.host.VirtualSwitch-vSwitch0</vswitch> <computedPolicy> <security> <allowPromiscuous>false</allowPromiscuous> <macChanges>true</macChanges> <forgedTransmits>true</forgedTransmits> </security> <nicTeaming> <policy>loadbalance_srcid</policy> <reversePolicy>true</reversePolicy> <notifySwitches>true</notifySwitches> <rollingOrder>false</rollingOrder> <failureCriteria> <checkSpeed>minimum</checkSpeed> <speed>10</speed> <checkDuplex>false</checkDuplex> <fullDuplex>false</fullDuplex>
943
<checkErrorPercent>false</checkErrorPercent> <percentage>0</percentage> <checkBeacon>false</checkBeacon> </failureCriteria> <nicOrder> <activeNic>vmnic0</activeNic> </nicOrder> </nicTeaming> <offloadPolicy> <csumOffload>true</csumOffload> <tcpSegmentation>false</tcpSegmentation> <zeroCopyXmit>true</zeroCopyXmit> </offloadPolicy> <shapingPolicy> <enabled>false</enabled> </shapingPolicy> </computedPolicy> <spec> <name>VM Network</name> <vlanId>0</vlanId> <vswitchName>vSwitch0</vswitchName> <policy> <security/> <nicTeaming> <failureCriteria/> </nicTeaming> <offloadPolicy/> <shapingPolicy/> </policy> </spec> </portgroup> <pnic> <key>key-vim.host.PhysicalNic-vmnic0</key> <device>vmnic0</device> <pci>06:07.0</pci> <driver>e1000</driver> <linkSpeed> <speedMb>1000</speedMb> <duplex>true</duplex> </linkSpeed> <validLinkSpecification> <speedMb>10</speedMb> <duplex>false</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>10</speedMb> <duplex>true</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>100</speedMb> <duplex>false</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>100</speedMb> <duplex>true</duplex> </validLinkSpecification>
944
<validLinkSpecification> <speedMb>1000</speedMb> <duplex>true</duplex> </validLinkSpecification> <spec> <ip> <dhcp>false</dhcp> <ipAddress/> <subnetMask/> </ip> </spec> </pnic> <pnic> <key>key-vim.host.PhysicalNic-vmnic1</key> <device>vmnic1</device> <pci>07:08.0</pci> <driver>e1000</driver> <validLinkSpecification> <speedMb>10</speedMb> <duplex>false</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>10</speedMb> <duplex>true</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>100</speedMb> <duplex>false</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>100</speedMb> <duplex>true</duplex> </validLinkSpecification> <validLinkSpecification> <speedMb>1000</speedMb> <duplex>true</duplex> </validLinkSpecification> <spec> <ip> <dhcp>false</dhcp> <ipAddress/> <subnetMask/> </ip> </spec> </pnic> <vnic> <device>portgroup8</device> <key>key-vim.host.VirtualNic-portgroup8</key> <portgroup>VM Network 1</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>127.21.10.10</ipAddress> <subnetMask>255.255.255.0</subnetMask> </ip> <mac>00:50:56:6e:bf:93</mac>
945
</spec> <port>key-vim.host.PortGroup.Port-16777221</port> </vnic> <vnic> <device>portgroup12</device> <key>key-vim.host.VirtualNic-portgroup12</key> <portgroup>Virtual Machine Network 2</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>127.21.10.10</ipAddress> <subnetMask>255.255.255.0</subnetMask> </ip> <mac>00:50:56:6e:0b:4b</mac> </spec> <port>key-vim.host.PortGroup.Port-67108870</port> </vnic> <consoleVnic> <device>vswif0</device> <key>key-vim.host.VirtualNic-vswif0</key> <portgroup>Service Console</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>127.21.10.12</ipAddress> <subnetMask>255.255.255.0</subnetMask> </ip> <mac>00:50:56:4b:c5:27</mac> </spec> <port>key-vim.host.PortGroup.Port-16777219</port> </consoleVnic> <dnsConfig> <dhcp>false</dhcp> <hostName>BMC-8</hostName> <domainName>bmc.com</domainName> <address>127.21.10.252</address> <searchDomain>bmc.com</searchDomain> </dnsConfig> <ipRouteConfig/> <consoleIpRouteConfig> <defaultGateway>127.21.10.22</defaultGateway> <gatewayDevice>vswif0</gatewayDevice> </consoleIpRouteConfig> </HostNetworkInfo> </propSet>
946
</returnval> </RetrieveHostNetworkConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements that provides details about the host network. Adapter response elements for the Retrieve_Host_Network_Configuration operation Element vswitch portgroup pnic vnic consoleVnic dnsConfig ipRouteConfig Definition The virtual switch configured on the network Portgroups configured on the host Physical network adapters as used by the primary operating system Virtual network adapters configured for use by the host operating system network adapter Virtual network adapters configured for use by the Service Console Client side DNS configuration for the host. The DNS configuration is global to the host IP route configuration of the host
consoleIpRouteConfig IP route configuration of the service console
Request and response for the Retrieve_Host_Datastore_Configuration operation

This operation retrieves the datastore details of the host including total space and free space. The following table describes the elements for this request. Adapter request elements for the Retrieve_Host_Datastore_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Host_Datastore_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
947
transport
No
Contains the data types and elements of the operation DNS name of the host for which the datastore configuration details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Host_Datastore_Configuration operation. Sample adapter request for the Retrieve_Host_Datastore_Configuration operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_Datastore_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_Datastore_Configuration operation. Sample adapter response for the Retrieve_Host_Datastore_Configuration operation
948
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostDatastoreConfigurationResponse> <returnval> <Datastore>datastore-116</Datastore> <propSet> <name>summary</name> <DatastoreSummary> <Datastore>datastore-116</Datastore> <name>storage1</name> <url>sanfs://vmfs_uuid:482046a1-90936125-4bd9-001422112dac/</url>
The following table describes the response elements. Adapter response elements for the Retrieve_Host_Datastore_Configuration operation Element accessible Definition The connectivity status of the datastore A value of false indicates that the datastore is not accessible, and the datastore's capacity and free space properties cannot be validated. Maximum capacity of the datastore, in bytes Available space of the datastore, in bytes
capacity freeSpace
multipleHostAccess A value of true indicates that more than one host in the datacenter has been configured with access to the datastore name type The name of the datastore The type of file system volume, such as VMFS or NFS
Request and response for the Retrieve_Virtual_Switch_Configuration operation

This operation retrieves details about the virtual switch of the host network. The following table describes the elements for this request. Adapter request elements for the Retrieve_Virtual_Switch_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Virtual_Switch_Configuration.
949
soap-url
No
transport
No
parameters host-system user-name
Contains the data types and elements of the operation DNS name of the host for which the virtual switch details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Retrieve_Virtual_Switch_Configuration operation. Sample adapter request for the Retrieve_Virtual_Switch_Configuration operation
950
<vmware-infrastructure-request> <user-name></user-name> <password></password> <soap-url></soap-url> <transport></transport> <operation-type>Host</operation-type> <operation-name>Retrieve_Virtual_Switch_Configuration</operation-name> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Virtual_Switch_Configuration operation. Sample adapter response for the Retrieve_Virtual_Switch_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVirtualSwitchConfigurationResponse> <returnval> <HostNetworkSystem>networkSystem-75</HostNetworkSystem> <propSet> <name>networkInfo.vswitch</name> <ArrayOfHostVirtualSwitch> <HostVirtualSwitch> <name>vSwitch0</name> <key>key-vim.host.VirtualSwitch-vSwitch0</key> <numPorts>32</numPorts> <numPortsAvailable>28</numPortsAvailable> <portgroup>key-vim.host.PortGroup-VM Network 1</portgroup> <portgroup>key-vim.host.PortGroup-VM Network</portgroup> <portgroup>key-vim.host.PortGroup-Service Console</portgroup> <pnic>key-vim.host.PhysicalNic-vmnic0</pnic> <spec> <numPorts>32</numPorts> <HostVirtualSwitchBondBridge> <nicDevice>vmnic0</nicDevice> <beacon> <interval>1</interval> </beacon> </HostVirtualSwitchBondBridge> <policy> <security> <allowPromiscuous>false</allowPromiscuous> <macChanges>true</macChanges> <forgedTransmits>true</forgedTransmits> </security> <nicTeaming> <policy>loadbalance_srcid</policy> <reversePolicy>true</reversePolicy>
951
<notifySwitches>true</notifySwitches> <rollingOrder>false</rollingOrder> <failureCriteria> <checkSpeed>minimum</checkSpeed> <speed>10</speed> <checkDuplex>false</checkDuplex> <fullDuplex>false</fullDuplex> <checkErrorPercent>false</checkErrorPercent> <percentage>0</percentage> <checkBeacon>false</checkBeacon> </failureCriteria> <nicOrder> <activeNic>vmnic0</activeNic> </nicOrder> </nicTeaming> <offloadPolicy> <csumOffload>true</csumOffload> <tcpSegmentation>false</tcpSegmentation> <zeroCopyXmit>true</zeroCopyXmit> </offloadPolicy> <shapingPolicy> <enabled>false</enabled> </shapingPolicy> </policy> </spec> </HostVirtualSwitch> </ArrayOfHostVirtualSwitch> </propSet>
952
</returnval> </RetrieveVirtualSwitchConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response element that provides details about the host network virtual switch. Adapter response element for the Retrieve_Virtual_Switch_Configuration operation Element name numPorts Definition The name of the virtual switch The current number of ports for the virtual switch
numPortsAvailable The number of ports that are available on this virtual switch pnic portgroup The set of physical network adapters associated with the bridge The list of port groups configured for the virtual switch
Request and response for the Retrieve_Virtual_NIC_Configuration operation

This operation retrieves details about the virtual NIC of the host network. The following table describes the elements for this request. Adapter request elements for the Retrieve_Virtual_NIC_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Virtual_NIC_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
953
transport
No
parameters host-system user-name
Contains the data types and elements of the operation DNS name of the host for which the virtual NIC details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Retrieve_Virtual_NIC_Configuration operation. Sample adapter request for the Retrieve_Virtual_NIC_Configuration operation
<vmware-infrastructure-request> <user-name></user-name> <password></password> <soap-url></soap-url> <transport></transport> <operation-type>Host</operation-type> <operation-name>Retrieve_Virtual_NIC_Configuration</operation-name> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Virtual_NIC_Configuration operation. Sample adapter response for the Retrieve_Virtual_NIC_Configuration operation
954
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVirtualNICConfigurationResponse> <returnval> <HostNetworkSystem>networkSystem-75</HostNetworkSystem> <propSet> <name>networkInfo.vnic</name> <ArrayOfHostVirtualNic> <HostVirtualNic> <device>portgroup8</device> <key>key-vim.host.VirtualNic-portgroup8</key> <portgroup>VM Network 1</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>127.21.10.252</ipAddress> <subnetMask>255.255.255.0</subnetMask> <ip> <mac>00:50:56:6e:bf:93</mac> </spec> <port>key-vim.host.PortGroup.Port-16777221</port> </HostVirtualNic> <HostVirtualNic> <device>portgroup12</device> <key>key-vim.host.VirtualNic-portgroup12</key> <portgroup>Virtual Machine Network 2</portgroup> <spec> <ip> <dhcp>false</dhcp> <ipAddress>127.21.10.22</ipAddress> <subnetMask>255.255.255.0</subnetMask> </ip> <mac>00:50:56:6e:0b:4b</mac> </spec> <port>key-vim.host.PortGroup.Port-67108870</port> </HostVirtualNic> </ArrayOfHostVirtualNic> </propSet> </returnval> </RetrieveVirtualNICConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements that provides details about the virtual NIC. Adapter response elements for the Retrieve_Virtual_NIC_Configuration operation Element port Definition The port on the port group that the virtual network adapter is using when it is enabled
portgroup The name of port group to which virtual nic is connected
955
spec device
The configurable properties for the virtual network adapter object The device name for the Virtual NIC
Request and response for the Retrieve_Port_Group_Configuration operation

This operation retrieves details about the port group of the host network. The following table describes the elements for this request. Adapter request elements for the Retrieve_Port_Group_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Port_Group_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system user-name Contains the data types and elements of the operation DNS name of the host for which the port group details are to be retrieved Valid values: dns name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes No
password
Conditional Required if the user-name is provided
956
The following code sample shows a sample adapter request for the Retrieve_Port_Group_Configuration operation. Sample adapter request for the Retrieve_Port_Group_Configuration operation
<vmware-infrastructure-request> <user-name></user-name> <password></password> <soap-url></soap-url> <transport></transport> <operation-type>Host</operation-type> <operation-name>Retrieve_Port_Group_Configuration</operation-name> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Port_Group_Configuration operation. Sample adapter response for the Retrieve_Port_Group_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrievePortGroupConfigurationResponse> <returnval> <HostNetworkSystem>networkSystem-75</HostNetworkSystem> <propSet> <name>networkInfo.portgroup</name> <ArrayOfHostPortGroup> <HostPortGroup> <key>key-vim.host.PortGroup-VM Network</key> <vswitch>key-vim.host.VirtualSwitch-vSwitch0</vswitch> <computedPolicy> <security> <allowPromiscuous>false</allowPromiscuous> <macChanges>true</macChanges> <forgedTransmits>true</forgedTransmits> </security> <nicTeaming> <policy>loadbalance_srcid</policy> <reversePolicy>true</reversePolicy> <notifySwitches>true</notifySwitches> <rollingOrder>false</rollingOrder> <failureCriteria> <checkSpeed>minimum</checkSpeed> <speed>10</speed> <checkDuplex>false</checkDuplex> <fullDuplex>false</fullDuplex> <checkErrorPercent>false</checkErrorPercent> <percentage>0</percentage>
957
<checkBeacon>false</checkBeacon> </failureCriteria> <nicOrder> <activeNic>vmnic0</activeNic> </nicOrder> </nicTeaming> <offloadPolicy> <csumOffload>true</csumOffload> <tcpSegmentation>false</tcpSegmentation> <zeroCopyXmit>true</zeroCopyXmit> </offloadPolicy> <shapingPolicy> <enabled>false</enabled> </shapingPolicy> </computedPolicy> <spec> <name>VM Network</name> <vlanId>0</vlanId> <vswitchName>vSwitch0</vswitchName> <policy> <security/> <nicTeaming> <failureCriteria/> </nicTeaming> <offloadPolicy/> <shapingPolicy/> </policy> </spec> </HostPortGroup> </ArrayOfHostPortGroup> </propSet>
958
</returnval> </RetrievePortGroupConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Port_Group_Configuration operation Element Definition
computedPolicy Computed network policies that are applicable for a port group port spec vswitch The ports that currently exist and are used on this port group The specification of a port group The virtual switch that contains this port group
Request and response for the Retrieve_Available_Disks_For_Vmfs operation

This operation enables you to retrieve a list of disks that can be used to contain new VMFS datastores. This operation filters out the management Logical Unit Numbers (LUNs) and disks that are referenced by Raw Device Mappings (RDMs). VMware VMFS cannot use such disk LUNs. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Available_Disks_For_Vmfs operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Available_Disks_For_Vmfs. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
959
transport
No
Contains the data types and elements of the operation Specifies the DNS name for the host from which you want to retrieve available disks for VMFS This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows the sample adapter request for the Retrieve_Available_Disks_For_Vmfs operation. Sample adapter request for the Retrieve_Available_Disks_For_Vmfs operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Available_Disks_For_Vmfs</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Available_Disks_For_Vmfs operation. Sample adapter response for the Retrieve_Available_Disks_For_Vmfs operation
960
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveAvailableDisksForVmfsResponse> <returnval>
<deviceName>/vmfs/devices/disks/vml.020001000060a980006e424f4f6c4a57786c716f624c554e202020</dev <deviceType>disk</deviceType> <key>key-vim.host.ScsiDisk-vmhba32:2:1</key> <uuid>020001000060a980006e424f4f6c4a57786c716f624c554e202020</uuid> <canonicalName>vmhba32:2:1</canonicalName> <lunType>disk</lunType> <vendor>NETAPP </vendor> <model>LUN </model> <revision>7320</revision> <scsiLevel>5</scsiLevel> <serialNumber>nBOOlJWxlqob</serialNumber> <operationalState>ok</operationalState> <capacity> <blockSize>512</blockSize> <block>1024000</block> </capacity> <devicePath>/vmfs/devices/disks/vml.020001000060a980006e424f4f6c4a57786c716f624c554e202020</dev </returnval> <returnval> <deviceName>/vmfs/devices/disks/vml.020000000060a980006e424f4f6c4a576b354737624c554e202020</dev <deviceType>disk</deviceType> <key>key-vim.host.ScsiDisk-vmhba32:2:0</key> <uuid>020000000060a980006e424f4f6c4a576b354737624c554e202020</uuid> <canonicalName>vmhba32:2:0</canonicalName> <lunType>disk</lunType> <vendor>NETAPP </vendor> <model>LUN </model> <revision>7320</revision> <scsiLevel>5</scsiLevel> <serialNumber>nBOOlJWk5G7b</serialNumber> <operationalState>ok</operationalState> <capacity> <blockSize>512</blockSize> <block>1024000</block> </capacity> <devicePath>/vmfs/devices/disks/vml.020000000060a980006e424f4f6c4a576b354737624c554e202020</dev </returnval> </RetrieveAvailableDisksForVmfsResponse> </vmware-infrastructure-response>
The following table shows the response elements for the Retrieve_Available_Disks_For_Vmfs operation. Adapter response elements for the Retrieve_Available_Disks_For_Vmfs operation Element ElementDefinition
961
HostSCSIDisk An array of data objects describing the available SCSI disks serialNumber The serialNumber for the available SCSI disk Note This element is only valid for NetApp Storage.
Request and response for the Retrieve_Host_CPU_Usage operation

This operation enables you to retrieve CPU information and current CPU usage on the specified host system. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Host_CPU_Usage operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Host_CPU_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system user-name Contains the data types and elements of the operation Specifies the DNS name of the host for which you want to retrieve CPU details This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration.
No
Yes Yes No
962
password
The following code sample shows the sample adapter request for the Retrieve_Host_CPU_Usage operation. Sample adapter request for the Retrieve_Host_CPU_Usage operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_CPU_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_CPU_Usage operation. Sample adapter response for the Retrieve_Host_CPU_Usage operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostCPUUsage> <returnval> <HostSystem>host-75</HostSystem> <propSet> <name>hardware.cpuInfo</name> <HostCpuInfo> <numCpuPackages>2</numCpuPackages> <numCpuCores>2</numCpuCores> <numCpuThreads>4</numCpuThreads> <hz>3591234072</hz> </HostCpuInfo> </propSet> <propSet> <name>summary.quickStats.overallCpuUsage</name> <hz>17000000</hz> </propSet> </returnval> </RetrieveHostCPUUsage> </vmware-infrastructure-response>
The following table shows the response elements for the Retrieve_Host_CPU_Usage operation. Adapter response elements for the Retrieve_Host_CPU_Usage operation
963
Element HostCPUInfo
Definition Contains information about the CPUs. numCpuCores - Number of physical CPU cores on the host numCpuPackages - Number of physical CPU packages on the host. numCpuThreads - Number of physical CPU threads on the host. hz - CPU speed per core The value of the hz element might be an averaged value if the speed is not uniform across all cores. The total CPU speed of the box is defined as hz * numCpuCores
overallCpuUsage Aggregated CPU usage across all cores on the host, in MHz. This element is available only if the host is connected.
Request and response for the Retrieve_Host_Memory_Usage operation

This operation enables you to retrieve the memory size and current memory usage for the specified host system. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Host_Memory_Usage operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Host_Memory_Usage. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation
No
No
Yes
964
host-system
Specifies the DNS name of the host for which you want to retrieve memory details This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes
user-name
No
password
The following code sample shows the sample adapter request for the Retrieve_Host_Memory_Usage operation. Sample adapter request for the Retrieve_Host_Memory_Usage operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_Memory_Usage</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_Memory_Usage operation. Sample adapter response for the Retrieve_Host_Memory_Usage operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostMemoryUsage> <returnval> <HostSystem>host-75</HostSystem> <propSet> <name>hardware.memorySize</name> <val>12884639744</val> </propSet> <propSet> <name>summary.quickStats.overallMemoryUsage</name> <val>603979776</val> </propSet> </returnval> </RetrieveHostMemoryUsage> </vmware-infrastructure-response>
The following table shows the response elements for the Retrieve_Host_Memory_Usage operation.
965
Adapter response elements for the Retrieve_Host_Memory_Usage operation Element memorySize Definition Specifies the total amount of physical memory available on the host system, in bytes
overallMemoryUsage Specifies the physical memory usage of the host system, in bytes. This element is available only if the host is connected.
Request and response for the Retrieve_ESX_Hosts operation

This operation retrieves the known ESX hosts and configuration on a VMware VirtualCenter, filtered by the specified cluster. The following table describes the elements for this request. Adapter request elements for Retrieve_ESX_Hosts operation Element operation-type operation-name soap-url Definition Defines the type of operation For this operation, the value of operation-type is Host. Defines the name of operation For this operation, the value of operation-name is Retrieve_ESX_Hosts. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation Yes No Required Yes Yes No
966
cluster-compute-resource Specifies the name of the cluster from which to retrieve ESX Hosts No The operation retrieves known ESX hosts and configuration on a VMware VirtualCenter, filtered by the specified cluster compute resource. If no value is specified, the operation retrieves all known hosts configured on the VMware VirtualCenter. Valid value: String user-name The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name No
password
The following code sample shows a sample adapter request for the Retrieve_ESX_Hosts operation. Sample adapter request for Retrieve_ESX_Hosts operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_ESX_Hosts</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <cluster-compute-resource>TestCluster</cluster-compute-resource> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Retrieve_ESX_Hosts operation. Sample adapter response for Retrieve_ESX_Hosts operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveESXHostsResponse> <returnval> <HostSystem>xyz.bmc.com</HostSystem> <propSet> <name>parent</name> <ClusterComputeResource>TestCluster</ClusterComputeResource> </propSet> <propSet> <name>summary</name> <HostListSummary> <HostSystem>xyz.bmc.com</HostSystem> <hardware>
967
<vendor>Dell Inc.</vendor> <model>PowerEdge 1950</model> <uuid>44454c4c-3200-1035-8044-b2c04f314431</uuid> <memorySize>34359377920</memorySize> <cpuModel>Intel) Xeon) CPU L5320 @ 1.86GHz</cpuModel> <cpuMhz>1862</cpuMhz> <numCpuPkgs>2</numCpuPkgs> <numCpuCores>8</numCpuCores> <numCpuThreads>8</numCpuThreads> <numNics>2</numNics> <numHBAs>1</numHBAs> </hardware> <runtime> <connectionState>connected</connectionState> <inMaintenanceMode>false</inMaintenanceMode> <bootTime>2009-09-03T16:37:20.193435Z</bootTime> </runtime> <config> <name>abc.bmc.com</name> <port>443</port> <product> <name>VMware ESX Server</name> <fullName>VMware ESX Server 3.5.0 build-110268</fullName> <vendor>VMware, Inc.</vendor> <version>3.5.0</version> <build>110268</build> <localeVersion>INTL</localeVersion> <localeBuild>000</localeBuild> <osType>vmnix-x86</osType> <productLineId>esx</productLineId> <apiType>HostAgent</apiType> <apiVersion>2.5u2</apiVersion> </product> <vmotionEnabled>false</vmotionEnabled> </config> <quickStats> <overallCpuUsage>1952</overallCpuUsage> <overallMemoryUsage>10669</overallMemoryUsage> <distributedCpuFairness>2360</distributedCpuFairness> <distributedMemoryFairness>719</distributedMemoryFairness> </quickStats> <overallStatus>green</overallStatus> <rebootRequired>false</rebootRequired> </HostListSummary> </propSet>
968
</returnval> </RetrieveESXHostsResponse> </vmware-infrastructure-response>
The following code sample describes the adapter response elements. Adapter response elements for the Retrieve_ESX_Hosts operation Element HostSystem Definition Name of the ESX Host configured on the VMware Virtual Center Server
ClusterComputeResource Represents the cluster to which the host system belongs HostListSummary Basic host statistics including basic configuration, hardware, and runtime information. The rebootRequired flag indicates whether the host requires a reboot due to a configuration change.
Request and response for the Retrieve_Host_Scsi_Topology operation

This operation enables you to retrieves the storage topology of SCSI storage devices for the specified host. This topology view organizes objects by SCSI interface, which contain targets that comprise of logical units. The following table describes the elements for this request. Adapter request elements for the Retrieve_Host_Scsi_Topology operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Host_Scsi_Topology. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port /sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
969
transport
No
Contains the data types and elements of the operation Specifies the name of the ESX host system for which you want to discover the storage topology of associated SCSI storage devices Valid value: String The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Host_Scsi_Topology operation. Sample adapter request for the Retrieve_Host_Scsi_Topology operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Retrieve_Host_Scsi_Topology</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>host1.xyz.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Host_Scsi_Topology operation. Sample adapter response for the Retrieve_Host_Scsi_Topology operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveHostScsiTopologyResponse> <returnval>

970
<HostStorageSystem>storageSystem-18</HostStorageSystem> <propSet> <name>storageDeviceInfo.scsiTopology</name> <HostScsiTopology> <adapter> <key>key-vim.host.ScsiTopology.Interface-vmhba32</key> <adapter>key-vim.host.InternetScsiHba-vmhba32</adapter> <target> <key>key-vim.host.ScsiTopology.Target-vmhba32:2</key> <target>2</target> <lun> <key>020000000060a980006e424f4f6c4a576b354737624c554e202020</key> <lun>0</lun> <scsiLun>key-vim.host.ScsiDisk-vmhba32:2:0</scsiLun> </lun> <lun> <key>020001000060a980006e424f4f6c4a57786c716f624c554e202020</key> <lun>1</lun> <scsiLun>key-vim.host.ScsiDisk-vmhba32:2:1</scsiLun> </lun> <HostInternetScsiTargetTransport> <iScsiName>iqn.1992-08.com.netapp:sn.99932695</iScsiName> <iScsiAlias /> <address>10.124.229.37:3160</address> </HostInternetScsiTargetTransport> </target> </adapter> <adapter> <key>key-vim.host.ScsiTopology.Interface-vmhba0</key> <adapter>key-vim.host.BlockHba-vmhba0</adapter> <target> <key>key-vim.host.ScsiTopology.Target-vmhba0:0</key> <target>0</target> <lun> <key>02000000005000c50003d6c1af535439373334</key> <lun>0</lun> <scsiLun>key-vim.host.ScsiDisk-vmhba0:0:0</scsiLun> </lun> <HostBlockAdapterTargetTransport/> </target> <target> <key>key-vim.host.ScsiTopology.Target-vmhba0:1</key> <target>1</target> <lun> <key>02000000005000c50003d6ba93535439373334</key> <lun>0</lun> <scsiLun>key-vim.host.ScsiDisk-vmhba0:1:0</scsiLun> </lun> <HostBlockAdapterTargetTransport/> </target> <target> <key>key-vim.host.ScsiTopology.Target-vmhba0:2</key> <target>2</target> <lun> <key>02000000005000c5000ab6b32f535439313436</key> <lun>0</lun>
971
<scsiLun>key-vim.host.ScsiDisk-vmhba0:2:0</scsiLun> </lun> <HostBlockAdapterTargetTransport/> </target> </adapter> </HostScsiTopology> </propSet>
972
</returnval> </RetrieveHostScsiTopologyResponse> </vmware-infrastructure-response>
Request and response for the Rescan_Hba operation

This operation allows you to issue a request for rescanning the specified host bus adapter on an ESX Server to detect new storage devices. The following table describes the elements for the adapter request. Adapter request elements for the Rescan_Hba operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Rescan_Hba. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name for the host for which you want to rescan the bus adapter Valid value: String Specifies the device on the host bus adapter that you want to scan Valid value: String
No
Yes Yes
hba-device
Yes
973
user-name
No
password
The following code sample shows the sample adapter request for the Rescan_Hba operation. Sample adapter request for the Rescan_Hba operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Rescan_Hba</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <hba-device>vmhba32</hba-device> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Rescan_Hba operation. Sample adapter response for the Rescan_Hba operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RescanHbaResponse></RescanHbaResponse> </vmware-infrastructure-response>
Request and response for the Rescan_All_Hba operation

This operation allows you to issue a request to rescan all host bus adapters on a ESX server for detecting new storage devices. The following table describes the elements for the adapter request. Adapter request elements for the Rescan_All_Hba operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes
974
operation-name Defines the name of operation For this operation, the value of operation-name is Rescan_All_Hba. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name for the host for which you want to rescan all bus adapters This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes No
No
Yes Yes
No
user-name password
The following code sample shows the sample adapter request for the Rescan_All_Hba operation. Sample adapter request for the Rescan_All_Hba operation
975
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Rescan_All_Hba</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Rescan_All_Hba operation. Sample adapter response for the Rescan_All_Hba operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RescanAllHbaResponse></RescanAllHbaResponse> </vmware-infrastructure-response>
Request and response for the Update_Host_Network_Configuration operation

This operation updates the network configuration of the host to the specified network. The following table describes the elements for this request. Adapter request elements for the Update_Host_Network_Configuration operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Host. Defines the name of the operation For this operation, the value of operation-name is Update_Host_Network_Configuration. Required Yes Yes
soap-url
Specifies the URL for the remote SOAP service running on the VMware No VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
976
transport
No
parameters host-system vswitch-list portgroup-list vnic-list
Contains the data types and elements of the operation DNS name of the host whose network configuration has to be updated Valid value: DNS name List of virtual switches configured on the host For information about the child elements, see vswitch-list. List of port groups configured on the host For information about the child elements, see portgroup-list. List of virtual network adapters configured for use by the host operating system network adapter For more information about the child elements of vnic-list, see vnic-list. List of virtual network adapters configured for use by the Service Console For more information about the child elements of console-vnic-list, see console-vnic-list. Indicates whether Dynamic Host Control Protocol (DHCP) is used to determine DNS configuration automatically Valid values: true, false If DHCP is enabled, the DHCP DNS of the service console network adapter will override the system DNS This element is ignored if DHCP is disabled by the dhcp property. The host name portion of DNS name For example, "esx01". Note: When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set. The domain name portion of the DNS name. For example, "vmware.com" Note: When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set List of the IP addresses of the DNS servers, placed in order of preference Note: When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set. For more information about the child elements, see address-list.
Yes Yes No No No
console-vnic-list
No
dhcp
No
virtual-nic-device
No
host-name
No
domain-name
No
address-list
No
977
search-domain-list
List of the domain in which to search for hosts, placed in order of preference Note: When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set. For more information about the child elements, see search-domain-list. Specifies the IP route configuration of the host For more information about the child elements, see ip-route-config.
No
ip-route-config
No No
console-ip-route-config IP route configuration of the service console For more information about the child elements, see console-ip-route-config. user-name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
No
password
The following code sample shows a sample adapter request to add a virtual switch, port group, and a virtual NIC. Sample adapter request for the Update_Host_Network_Configuration operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Update_Host_Network_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vswitch-list> <vswitch> <change-operation>add</change-operation> <name>vSwitch1</name> <spec> <num-ports>8</num-ports> <policy> <security> <allow-promiscuous>true</allow-promiscuous> <mac-changes>false</mac-changes> <forged-transmits>false</forged-transmits> </security> <nic-teaming> <policy>failover_explicit</policy> <reverse-policy>true</reverse-policy> <notify-switches>false</notify-switches> <rolling-order>true</rolling-order>
978
<failure-criteria> <check-speed>exact</check-speed> <speed>32</speed> <check-duplex>true</check-duplex> <full-duplex>true</full-duplex> <check-error-percent>true</check-error-percent> <percentage>50</percentage> <check-beacon>false</check-beacon> </failure-criteria> <nic-order> <active-nic-list> <active-nic></active-nic> <active-nic></active-nic> </active-nic-list> <standby-nic-list> <standby-nic></standby-nic> <standby-nic></standby-nic> </standby-nic-list> </nic-order> </nic-teaming> <offload-policy> <csum-offload>false</csum-offload> <tcp-segmentation>false</tcp-segmentation> <zero-copy-xmit>false</zero-copy-xmit> </offload-policy> <shaping-policy> <enabled>true</enabled> <average-bandwidth>102400</average-bandwidth> <peak-bandwidth>102400</peak-bandwidth> <burst-size>102400</burst-size> </shaping-policy> </policy> </spec> </vswitch> <vswitch> <change-operation>add</change-operation> <name>vSwitch2</name> <spec> <num-ports>24</num-ports> </spec> </vswitch> </vswitch-list> <portgroup-list> <portgroup> <change-operation>add</change-operation> <spec> <name>VM Network</name> <vlan-id>0</vlan-id> <vswitch-name>vSwitch1</vswitch-name> <policy> <security> <allow-promiscuous>false</allow-promiscuous> <mac-changes>true</mac-changes> <forged-transmits>true</forged-transmits> </security> <nic-teaming>
979
<policy></policy> <reverse-policy></reverse-policy> <notify-switches></notify-switches> <rolling-order></rolling-order> <failure-criteria> <check-speed></check-speed> <speed></speed> <check-duplex></check-duplex> <full-duplex></full-duplex> <check-error-percent></check-error-percent> <percentage></percentage> <check-beacon></check-beacon> </failure-criteria> <nic-order> <active-nic-list> <active-nic></active-nic> <active-nic></active-nic> </active-nic-list> <standby-nic-list> <standby-nic></standby-nic> <standby-nic></standby-nic> </standby-nic-list> </nic-order> </nic-teaming> <offload-policy> <csum-offload></csum-offload> <tcp-segmentation></tcp-segmentation> <zero-copy-xmit></zero-copy-xmit> </offload-policy> <shaping-policy> <enabled></enabled> <average-bandwidth></average-bandwidth> <peak-bandwidth></peak-bandwidth> <burst-size></burst-size> </shaping-policy> </policy> </spec> </portgroup> <portgroup> <change-operation>add</change-operation> <spec> <name>Service Console</name> <vlan-id>0</vlan-id> <vswitch-name>vSwitch1</vswitch-name> </spec> </portgroup> </portgroup-list> <vnic-list> <vnic> <change-operation>add</change-operation> <portgroup>VM Network</portgroup> <spec> <ip> <dhcp>false</dhcp> <ip-address>127.21.10.10</ip-address> <subnet-mask>255.255.255.0</subnet-mask>
980
</ip> <mac></mac> </spec> </vnic> </vnic-list> <console-vnic-list> <console-vnic> <change-operation></change-operation> <device></device> <portgroup></portgroup> <spec> <ip> <dhcp></dhcp> <ip-address></ip-address> <subnet-mask></subnet-mask> </ip> <mac></mac> </spec> </console-vnic> </console-vnic-list> <dnsConfig> <dhcp></dhcp> <virtual-nic-device></virtual-nic-device> <host-name></host-name> <domain-name></domain-name> <address-list> <address></address> <address></address> </address-list> <search-domain-list> <search-domain></search-domain> <search-domain></search-domain> </search-domain-list> </dnsConfig> <ip-route-config> <default-gateway></default-gateway> </ip-route-config> <console-ip-route-config> <default-gateway></default-gateway> <gateway-device></gateway-device> </console-ip-route-config>
981
The following code sample shows a sample adapter request to remove a virtual switch, port group, or a virtual NIC. Sample adapter request for the Update_Host_Network_Configuration operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Update_Host_Network_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vswitch-list> <vswitch> <change-operation>remove</change-operation> <name>vSwitch1</name> </vswitch> <vswitch> <change-operation>remove</change-operation> <name>vSwitch2</name> </vswitch> </vswitch-list> <portgroup-list> <portgroup> <change-operation>remove</change-operation> <spec> <name>VM Network</name> </spec> </portgroup> </portgroup-list> <vnic-list> <vnic> <change-operation>remove</change-operation> <portgroup>VM Network</portgroup> </vnic> </vnic-list> <console-vnic-list> <console-vnic> <change-operation></change-operation> <device></device> <portgroup></portgroup> <spec> <ip> <dhcp></dhcp> <ip-address></ip-address> <subnet-mask></subnet-mask>
982
</ip> <mac></mac> </spec> </console-vnic> </console-vnic-list> <dnsConfig> <dhcp></dhcp> <virtual-nic-device></virtual-nic-device> <host-name></host-name> <domain-name></domain-name> <address-list> <address></address> <address></address> </address-list> <search-domain-list> <search-domain></search-domain> <search-domain></search-domain> </search-domain-list> </dnsConfig> <ip-route-config> <default-gateway></default-gateway> </ip-route-config> <console-ip-route-config> <default-gateway></default-gateway> <gateway-device></gateway-device> </console-ip-route-config>
983
The following code sample shows the response for the sample Update_Host_Network_Configuration operation. Sample adapter response for the Update_Host_Network_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateNetworkConfigResponse> <returnval/> </UpdateNetworkConfigResponse> </vmware-infrastructure-response>
Request and response for the Extend_Vmfs_Datastore operation

This operation enables you to extend an existing VMFS datastore. The following table describes the elements for the adapter request. Adapter request elements for the Extend_Vmfs_Datastore operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes
operation-name Defines the name of operation Yes For this operation, the value of operation-name is Extend_Vmfs_Datastore. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. No
984
transport
No
Contains the data types and elements of the operation Specifies the DNS name for the host for which you want to extend the VMFS datastore This element can contain only string values. Specifies the name of the disk that can be used to extend the VMFS datastore This element can contain only string values.
Yes Yes
disk-name
Conditional Required if the serial-number element is not specified Conditional Required if the disk-name element is not specified
serial-number
Specifies the serial number of the disk that can be used to extend the VMFS datastore Note This element is only valid for NetApp Storage.
datastore user-name
Specifies the name of the datastore that you want to extend This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes No
password
The following code sample shows a sample adapter request for the Extend_Vmfs_Datastore operation with the serial-number element. Sample adapter request for the Extend_Vmfs_Datastore operation with the serial-number element
985
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Extend_Vmfs_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <serial-number>nBOOIJWk5G7B</serial-number> <datastore>SAN2</datastore> </parameters> </vmware-infrastructure-request>
The following code sample shows a sample adapter request for the Extend_Vmfs_Datastore operation with the disk-name element. Sample adapter request for the Extend_Vmfs_Datastore operation with the disk-name element
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Extend_Vmfs_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <disk-name>vmhba32:1:1</disk-name> <datastore>SAN2</datastore> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Extend_Vmfs_Datastore operation. Sample adapter response for the Extend_Vmfs_Datastore operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ExtendVmfsDatastoreResponse> <Datastore>datastore-6152</Datastore> </ExtendVmfsDatastoreResponse> </vmware-infrastructure-response>
The following code sample shows the response elements for the Extend_Vmfs_Datastore operation. Adapter response elements for the Extend_Vmfs_Datastore operation
986
Element
Definition
Datastore the extended datastore
Request and response for the Update_Software_Internet_Scsi_Enabled operation

This operation allows you to enable or disable an Internet SCSI. The following table describes the elements for the adapter request. Adapter request elements for the Update_Software_Internet_Scsi_Enabled operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Update_Software_Internet_Scsi_Enabled. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name of the host on which you want to enable the Internet SCSI This element can contain only string values. Specifies whether the Internet SCSI is enabled The valid values for this element are True or False. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration.
No
No
Yes Yes
enabled user-name
Yes No
987
password
The following code sample shows the sample adapter request for the Update_Software_Internet_Scsi_Enabled operation. Sample adapter request for the Update_Software_Internet_Scsi_Enabled operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Update_Software_Internet_Scsi_Enabled </operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <enabled>true</enabled> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_Software_Internet_Scsi_Enabled operation. Sample adapter response for the Update_Software_Internet_Scsi_Enabled operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateSoftwareInternetScsiEnabledResponse> </UpdateSoftwareInternetScsiEnabledResponse> </vmware-infrastructure-response>
Request and response for the Update_Internet_Scsi_Name operation

This operation allows you to update the name of a Internet SCSI host bus adapter. The following table describes the elements for the adapter request. Adapter request elements for the Update_Internet_Scsi_Name operation Element operation-type operation-name Definition Defines the type of operation For this operation, the value of operation-type is Host. Defines the name of operation For this operation, the value of operation-name is Update_Internet_Scsi_Name. Required Yes Yes
988
soap-url
No
transport
No
Contains the data types and elements of the operation Specifies the DNS name of the host on which you want to update the name of the Internet SCSI host bus adapter This element can contain only string values.
Yes Yes
iScsi-hba-device Specifies the current name of the Internet SCSI host bus adapter This element can contain only string values. iScsi-name user-name Specifies the new name of the Internet SCSI host bus adapter This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows the sample adapter request for the Update_Internet_Scsi_Name operation. Sample adapter request for the Update_Internet_Scsi_Name operation
989
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Update_Internet_Scsi_Name</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <iScsi-hba-device>vmhba40</iScsi-hba-device> <iScsi-name>Test</iScsi-name> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_Internet_Scsi_Name operation. Sample adapter response for the Update_Internet_Scsi_Name operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateInternetScsiNameResponse></UpdateInternetScsiNameResponse> </vmware-infrastructure-response>
Request and response for the Remove_Host_From_Cluster operation

This operation removes a host from a cluster and makes it a standalone host. The following table describes the elements for this request. Adapter request elements for the Remove_Host_From_Cluster operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Remove_Host_From_Cluster.
990
soap-url
No
transport
No
parameters folder host-system datacenter user-name
Contains the data types and elements of the operation Contains the name of the folder to which the host is to be moved DNS name of the host to be moved into the folder Valid value: DNS name The name of the datacenter containing the host The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name
Yes Yes Yes Yes No
password
The following code sample shows a sample adapter request for the Remove_Host_From_Cluster operation. Sample adapter request for the Remove_Host_From_Cluster operation
991
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Remove_Host_From_Cluster</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <folder>host</folder> <host-system>xyz.bmc.com</host-system> <datacenter>BMC_DEV</datacenter> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Host_From_Cluster operation. Sample adapter response for the Remove_Host_From_Cluster operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveHostFromClusterResponse> <Task>task-734</Task> </RemoveHostFromClusterResponse> </vmware-infrastructure-response>
The following table describes the response element. Adapter response element for the Remove_Host_From_Cluster operation Element Definition Task Task ID of the task
Request and response for the Remove_Virtual_Switch operation

This operation updates the configuration of a host network to remove a virtual switch. Note Before removing a virtual switch, you must remove all virtual NICs associated with the virtual switch.
The following table describes the elements for this request. Adapter request elements for the Remove_Virtual_Switch operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes
992
operation-name Defines the name of the operation For this operation, the value of operation-name is Remove_Virtual_Switch. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation DNS name of the host on the network from which the virtual switch is to be removed Valid values: dns name The list of virtual switches to be removed from the host Values takes the form:
<vswitch-list> <vswitch> <name></name> </vswitch> ...... </vswitch-list>
Yes
No
No
Yes Yes operation-type Yes
vswitch-list
name: the name of the virtual switch user-name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name No
password
The following code sample shows a sample adapter request for the Remove_Virtual_Switch operation.
993
Sample adapter request for the Remove_Virtual_Switch operation

<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Remove_Virtual_Switch</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vswitch-list> <vswitch> <name>vSwitch4</name> </vswitch> </vswitch-list> </config> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Virtual_Switch operation. Sample adapter response for the Remove_Virtual_Switch operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveVirtualSwitchResponse> <returnval/> </RemoveVirtualSwitchResponse>
Request and response for the Remove_Virtual_NIC operation

This operation updates the configuration of a host network to remove a virtual NIC. The following table describes the elements for this request. Adapter request elements for the Remove_Virtual_NIC operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Remove_Virtual_NIC.
994
soap-url
No
transport
No
Contains the data types and elements of the operation DNS name of the host on the network from which the virtual NIC is to be removed Valid values: dns name The list of virtual network adapters to be removed from the host Format:
<vnic-list> <vnic> <portgroup> </portgroup> <vnic> <vnic-list>
Yes Yes
vnic-list
Yes
portgroup: The name of the port group for the virtual network adapter user-name The name of the user If no user name is specified, the request executes with the user specified in the configuration. The password corresponding to the specified user name No
password
Conditional Required if the user-name element is provided No
user-name
The name of the user If no user name is specified, the request is executed with the user specified in the configuration.
995
password
The following code sample shows a sample adapter request for the Remove_Virtual_NIC operation. Sample adapter request for the Remove_Virtual_NIC operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Remove_Virtual_NIC</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <vnic-list> <vnic> <portgroup>Virtual Machine Network 2</portgroup> </vnic> </vnic-list> </config> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Virtual_NIC operation. Sample adapter response for the Remove_Virtual_NIC operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveVirtualNICResponse> <returnval/> </RemoveVirtualNICResponse> </vmware-infrastructure-response>
Request and response for the Remove_Port_Group operation

This operation updates the configuration of a host network to remove a port group. Note Before removing a port group, you must remove all virtual NICs associated with the port group.
996
The following table describes the elements for this request. Adapter request elements for the Remove_Port_Group operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Remove_Port_Group. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation DNS name of the host on the network from which the virtual switch is to be deleted Valid values: dns name Contains the list of port groups to be removed on the host Values takes the form:
<portgroup-list> <portgroup> <spec> <name> </name> <spec> <portgroup> <portgroup-list>
No
Yes Yes
portgroup-list
Yes
name: Name of the port group Valid value: String
997
user-name
The name of the user No If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name Conditional Required if user-name is provided
password
The following figure shows a sample adapter request for the Remove_Port_Group operation. Sample adapter request for the Remove_Port_Group operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Remove_Port_Group</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <config> <portgroup-list> <portgroup> <spec> <name>VM Network 2</name> </spec> </portgroup> </portgroup-list> </config> </parameters> </vmware-infrastructure-request>
The following figure shows the response for the sample Remove_Port_Group operation. Sample adapter response for the Remove_Port_Group operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemovePortGroupResponse> <returnval/> </RemovePortGroupResponse> <vmware-infrastructure-response>
Request and response for the Remove_Datastore operation

This operation enables you to remove a datastore from a host system.
998
Note You cannot remove a datastore if a virtual machine is registered to any host attached to the datastore.
The following table describes the elements for the adapter request. Adapter request elements for the Remove_Datastore operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Host. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Remove_Datastore. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name of the host from which you want to remove the datastore This element can contain only string values. Specifies the datastore that you want to remove This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes
datastore user-name
Yes No
password
999
The following code sample shows the sample adapter request for the Remove_Datastore operation. Sample adapter request for the Remove_Datastore operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Remove_Datastore</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>rba-dev15.bmc.com</host-system> <datastore>NetAppNASStorage1</datastore> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Remove_Datastore operation. Sample adapter response for the Remove_Datastore operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RemoveDatastoreResponse></RemoveDatastoreResponse> </vmware-infrastructure-response>
Request and response for the Enter_Maintenance_Mode operation

This operation enables you to put the specified host in the maintenance mode. If you are executing this operation and the host is in maintenance mode, you cannot power on virtual machines or perform provisioning operations on the host. After the operation completes, it is safe to turn off a host without disrupting any virtual machines. The operation completes if there are no powered-on virtual machines on the host and no provisioning operations are in progress on the host. The operation does not directly initiate any operations to evacuate or power-down virtual machines. However, if the host is part of a cluster with VMware DRS enabled, DRS provides migration recommendations to evacuate the virtual machines. If DRS is in fully-automatic mode, the migrations are automatically scheduled. Note The operation is cancellable.
The following table describes the elements for the adapter request. Adapter request elements for the Enter_Maintenance_Mode operation Element Definition Required
Copyright 2009 -- 2011 BladeLogic, Inc. BMC, BMC Software, the BMC logos, and other BMC marks are trademarks or registered trademarks of BMC Software, Inc. in the U.S. and/or certain other countries. BladeLogic and the BladeLogic logo are trademarks or registered trademarks of BladeLogic, Inc. in the U.S. and/or certain other countries. All other trademarks 1000 or registered trademarks are the property of their respective owners. BMC Software Confidential.
operation-type
Defines the type of operation For this operation, the value of operation-type is Host.
Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Enter_Maintenance_Mode. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name for the host that you want to put into the maintenance mode This element can contain only string values. The operation completes when the host successfully enters maintenance mode or the timeout expires. If the timeout expires, the task contains a timeout fault. If this element is less than or equal to zero, no timeout occurs. This element can contain only integer values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes
timeout
Yes
user-name
No
password
The following code sample shows the sample adapter request for the Enter_Maintenance_Mode operation. Sample adapter request for the Enter_Maintenance_Mode operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Enter_Maintenance_Mode</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <timeout>0</timeout> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Enter_Maintenance_Mode operation. Sample adapter response for the Enter_Maintenance_Mode operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <EnterMaintenanceMode_TaskResponse> <Task>task-7983</Task> </EnterMaintenanceMode_TaskResponse> </vmware-infrastructure-response>
The following table shows the response element for the Enter_Maintenance_Mode operation. Adapter response element for the Enter_Maintenance_Mode operation Element Definition Task the task ID of the submitted task
Request and response for the Exit_Maintenance_Mode operation

This operation takes the host out of maintenance mode. This operation is blocked if any concurrent running maintenance-only host configurations operations are being performed on the specified host. For example, if the VMFS volumes are being upgraded. Note You can cancel this operation.
The following table describes the elements for the adapter request. Adapter request elements for the Exit_Maintenance_Mode operation Element Definition Required
operation-type
Defines the type of operation For this operation, the value of operation-type is Host.
Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Exit_Maintenance_Mode. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters host-system Contains the data types and elements of the operation Specifies the DNS name for the host that you want to take out of the maintenance mode This element can contain only string values. Specifies the number of seconds to wait for the exit maintenance mode operation to succeed If this element is less than or equal to zero, no timeout occurs. This element can contain only integer values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes
timeout
Yes
user-name
No
password
The following code sample shows the sample adapter request for the Exit_Maintenance_Mode operation. Sample adapter request for the Exit_Maintenance_Mode operation
<vmware-infrastructure-request> <operation-type>Host</operation-type> <operation-name>Exit_Maintenance_Mode</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <host-system>xyz.bmc.com</host-system> <timeout>0</timeout> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Exit_Maintenance_Mode operation. Sample adapter response for the Exit_Maintenance_Mode operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ExitMaintenanceMode_TaskResponse> <Task>task-7984</Task> </ExitMaintenanceMode_TaskResponse> </vmware-infrastructure-response>
The following table shows the response element for the Exit_Maintenance_Mode operation. Adapter response elements for the Exit_Maintenance_Mode operation Element Definition Task the task ID of the submitted task
Adapter requests and responses for Datastore operations

The following topics illustrate the adapter requests and responses for the Datastore operations.
Request and response for the Retrieve_Datastore_List operation Request and response for the Retrieve_Datastore_Virtual_Machines operation Request and response for the Retrieve_Vmfs_Datastore_Storage_Controller operation
Request and response for the Retrieve_Datastore_List operation

This operation enables you to retrieve a list of datastores on a datacenter including information about the total space and free space available on each datastore. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Datastore_List operation
Definition Defines the type of operation For this operation, the value of operation-type is Datastore.
Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Datastore_List. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters datacenter user-name Contains the data types and elements of the operation Specifies the datacenter hosting the datastores that you want to retrieve This element can contain only string values. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes No
password
The following code sample shows the sample adapter request for the Retrieve_Datastore_List operation. Sample adapter request for the Retrieve_Datastore_List operation
<vmware-infrastructure-request> <operation-type>Datastore</operation-type> <operation-name>Retrieve_Datastore_List</operation-name> <parameters> <datacenter>DEV1</datacenter> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Datastore_List operation. Sample adapter response for the Retrieve_Datastore_List operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveDatastoreListResponse> <returnval> <Datastore>datastore-15</Datastore> <propSet> <name>summary</name> <DatastoreSummary> <Datastore>datastore-15</Datastore> <name>dev1 disk3</name> <url>sanfs://vmfs_uuid:48287d4e-aec12ab6-1d35-0019b9e1c5fe/</url> <capacity>146565758976</capacity> <freeSpace>17357078528</freeSpace> <accessible>true</accessible> <multipleHostAccess>false</multipleHostAccess> <type>VMFS</type> </DatastoreSummary> </propSet> </returnval> <returnval> <Datastore>datastore-11</Datastore> <propSet> <name>summary</name> <DatastoreSummary> <Datastore>datastore-11</Datastore> <name>dev1 disk2</name> <url>sanfs://vmfs_uuid:478d1b24-552c354d-c670-0019b9e1c5fe/</url> <capacity>73282879488</capacity> <freeSpace>5570035712</freeSpace> <accessible>true</accessible> <multipleHostAccess>false</multipleHostAccess> <type>VMFS</type> </DatastoreSummary> </propSet> </returnval> <returnval> <Datastore>datastore-11</Datastore> <propSet> <name>summary</name> <DatastoreSummary> <Datastore>datastore-11</Datastore> <name>storage2</name> <url>sanfs://vmfs_uuid:470e81f0-32b2d06a-a25c-0019b9e1c5fe/</url> <capacity>65229815808</capacity> <freeSpace>1514143744</freeSpace> <accessible>true</accessible> <multipleHostAccess>false</multipleHostAccess> <type>VMFS</type> </DatastoreSummary> </propSet> </returnval> </RetrieveDatastoreListResponse> </vmware-infrastructure-response>
Request and response for the Retrieve_Datastore_Virtual_Machines operation

This operation enables you to retrieve a list of all virtual machines registered on the specified datastore. The following table describes the elements for the adapter request. Adapter request elements for the Retrieve_Datastore_Virtual_Machines operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Datastore. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Datastore_Virtual_Machines. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters datacenter Contains the data types and elements of the operation Specifies the datacenter hosting the datastore This element can contain only string values.
No
No
Yes Conditional Required if duplicate datastores exist in different datacenters with the same name Yes
datastore
Specifies the datastore from which you want to retrieve the list of registered virtual machines This element can contain only string values.
user-name
No
password
The following code sample shows the sample adapter request for the Retrieve_Datastore_Virtual_Machines operation. Sample adapter request for the Retrieve_Datastore_Virtual_Machines operation
<vmware-infrastructure-request> <operation-type>Datastore</operation-type> <operation-name>Retrieve_Datastore_Virtual_Machines</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <datacenter>RBA_DEV</datacenter> <datastore>NetAppNASStorage1</datastore> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Datastore_Virtual_Machines operation. Sample adapter response for the Retrieve_Datastore_Virtual_Machines operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveDatastoreVirtualMachinesResponse> <returnval> <Datastore>dev15 disk2</Datastore> <propSet> <name>vm</name> <ArrayOfManagedObjectReference> <returnval> <VirtualMachine>TemplateRomi</VirtualMachine> <template>true</template> </returnval> <returnval> <VirtualMachine>lcm-001</VirtualMachine> <template>false</template> </returnval> </ArrayOfManagedObjectReference> </propSet> </returnval> </RetrieveDatastoreVirtualMachinesResponse> </vmware-infrastructure-response>
The following table shows the response elements for the Retrieve_Datastore_Virtual_Machines operation. Adapter response elements for the Retrieve_Datastore_Virtual_Machines operation Element Definition
VirtualMachine The virtual machine registered on the datastore template The boolean value that indicates whether the virtual machine is a template
Request and response for the Retrieve_Vmfs_Datastore_Storage_Controller operation

This operation enables you to retrieves the volume information for the specified Vmfs datastore and corresponding SCSI Transport information about the target. The following table describes the elements for this request. Adapter request elements for the Retrieve_Vmfs_Datastore_Storage_Controller operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Datastore. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Vmfs_Datastore_Storage_Controller.
soap-url
No
transport
No
parameters datastore
Contains the data types and elements of the operation Specifies the name of the datastore for which you want to discover the volume information and corresponding SCSI transport information Valid value: String The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Vmfs_Datastore_Storage_Controller operation. Sample adapter request for the Retrieve_Vmfs_Datastore_Storage_Controller operation
<vmware-infrastructure-request> <operation-type>Datastore</operation-type> <operation-name>Retrieve_Vmfs_Datastore_Storage_Controller</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <datastore>TestVmfs</datastore> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Vmfs_Datastore_Storage_Controller operation. Sample adapter response for the Retrieve_Vmfs_Datastore_Storage_Controller operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveVmfsDatastoreStorageControllerResponse> <returnval> <Datastore>datastore-8011</Datastore> <propSet> <name>info</name> <VmfsDatastoreInfo> <name>TestVmfs </name> <url>sanfs://vmfs_uuid:4c5aaf43-d2673665-681c-0019b9e1c5fe/</url> <freeSpace>241172480</freeSpace> <maxFileSize>274877906944</maxFileSize> <vmfs> <type>VMFS</type> <name>TestVmfs</name> <capacity>268435456</capacity> <blockSizeMb>1</blockSizeMb> <maxBlocks>262144</maxBlocks> <majorVersion>3</majorVersion> <version>3.31</version> <uuid>4c5aaf43-d2673665-681c-0019b9e1c5fe</uuid> <extent> <diskName>vmhba32:2:1</diskName> <partition>1</partition> <HostInternetScsiTargetTransport> <iScsiName>iq1.1992-08.com.netapp:sn.99932695</iScsiName> <iScsiAlias></iScsiAlias> <address>10.128.249.37:3260</address> </HostInternetScsiTargetTransport> </extent> <vmfsUpgradable>false</vmfsUpgradable> </vmfs> </VmfsDatastoreInfo> </propSet> </returnval> </RetrieveVmfsDatastoreStorageControllerResponse> </vmware-infrastructure-response>
Adapter requests and responses for Cluster operations

The following topics illustrate the adapter requests and responses for the Cluster operations.
Request and response for the Retrieve_Cluster_Configuration operation Request and response for the Retrieve_Cluster_Datastore_Configuration operation Request and response for the Retrieve_Clusters operation Request and response for the Update_Cluster_DRS_Configuration operation
Request and response for the Retrieve_Cluster_Configuration operation

This operation retrieves the configuration details of a cluster including Distributed Resource Scheduler (DRS)
settings. The following table describes the elements for this request. Adapter request elements for the Retrieve_Cluster_Configuration operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Cluster. Defines the name of the operation For this operation, the value of operation-name is Retrieve_Cluster_Configuration. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation Yes Yes No No Required Yes Yes
soap-url
No
cluster-compute-resource The name of the cluster whose details are to be retrieved Valid value: String user-name The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
password
The following code sample shows a sample adapter request for the Retrieve_Cluster_Configuration operation.
Sample adapter request for the Retrieve_Cluster_Configuration operation

<vmware-infrastructure-request> <operation-type>Cluster</operation-type> <operation-name>Retrieve_Cluster_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <username></username> <password></password> <parameters> <cluster-compute-resource>DRS Cluster TEST</cluster-compute-resource> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Cluster_Configuration operation. Sample adapter response for the Retrieve_Cluster_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveClusterConfigurationResponse> <returnval> <ClusterComputeResource>DRS Cluster TESTdomain</ClusterComputeResource> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>configuration</name> <ClusterConfigInfo> <dasConfig> <enabled>false</enabled> <failoverLevel>1</failoverLevel> <admissionControlEnabled>true</admissionControlEnabled> </dasConfig> <drsConfig> <enabled>true</enabled> <defaultVmBehavior>manual</defaultVmBehavior> <vmotionRate>3</vmotionRate> </drsConfig> </ClusterConfigInfo> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet>
<propSet> <name>datastore</name> <ArrayOfManagedObjectReference> <Datastore>datastore-11</Datastore> <Datastore>datastore-13</Datastore> <Datastore>datastore-15</Datastore> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.domain-c614</key> <ClusterComputeResource>domain-c614</ClusterComputeResource> <Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-08-24T14:12:24.171875Z</time> </AlarmState> <AlarmState> <key>alarm-104.domain-c614</key> <ClusterComputeResource>domain-c614</ClusterComputeResource> <Alarm>alarm-104</Alarm> <overallStatus>gray</overallStatus> <time>2009-08-24T14:12:24.296875Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>drsRecommendation</name> <ArrayOfClusterDrsRecommendation></ArrayOfClusterDrsRecommendation> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>environmentBrowser</name> <EnvironmentBrowser>envbrowser-614</EnvironmentBrowser> </propSet> <propSet> <name>host</name> <ArrayOfManagedObjectReference> <HostSystem>xyz.bmc.com</HostSystem> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>migrationHistory</name> <ArrayOfClusterDrsMigration></ArrayOfClusterDrsMigration> </propSet> <propSet>
<name>name</name> <val>DRS Cluster TEST</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference> <Network>network-3587</Network> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>group-h4</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <ClusterComputeResource>domain-c614</ClusterComputeResource> <principal>qauser</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> </ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>resourcePool</name> <ResourcePool>resgroup-616</ResourcePool> </propSet> <propSet> <name>summary</name> <ClusterComputeResourceSummary> <totalCpu>14896</totalCpu> <totalMemory>34359377920</totalMemory> <numCpuCores>8</numCpuCores> <numCpuThreads>8</numCpuThreads> <effectiveCpu>14430</effectiveCpu> <effectiveMemory>29930</effectiveMemory> <numHosts>1</numHosts> <numEffectiveHosts>1</numEffectiveHosts> <overallStatus>green</overallStatus> <currentFailoverLevel>-1</currentFailoverLevel> <numVmotions>0</numVmotions> </ClusterComputeResourceSummary> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState>
</propSet>
</returnval> </RetrieveClusterConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Cluster_Configuration operation Element configuration Definition Configuration of the VMware HA service (HA) and VMware DRS
drsRecommendation If DRS is enabled, this element returns a set of recommended migrations from the DRS module Even if DRS is enabled, the current set of recommendations may be empty since there may be no recommended migrations at this time. If DRS is not enabled, always returns an empty list. migrationHistory The set of migration decisions that have been recently performed
Request and response for the Retrieve_Cluster_Datastore_Configuration operation

This operation retrieves the datastore configuration of a cluster including total space and free space. The following table describes the elements for this request. Adapter request elements for the Retrieve_Cluster_Datastore_Configuration operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Cluster. Defines the name of the operation For this operation, the value of operation-name is Retrieve_Cluster_Datastore_Configuration. Contains the data types and elements of the operation Required Yes Yes
parameters
Yes Yes
cluster-compute-resource The name of the cluster whose datastore configuration details are to be retrieved Valid value: String user-name The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
No
password
The following code sample shows a sample adapter request for the Retrieve_Cluster_Datastore_Configuration operation. Sample adapter request for the Retrieve_Cluster_Datastore_Configuration operation
<vmware-infrastructure-request> <operation-type>Cluster</operation-type> <operation-name>Retrieve_Cluster_Datastore_Configuration</operation-name> <soap-url></soap-url> <transport></transport> <username>abc</username> <password>abc</password> <parameters> <cluster-compute-resource>DRS Cluster TEST </cluster-compute-resource> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Cluster_Datastore_Configuration operation.
Sample adapter response for the Retrieve_Cluster_Datastore_Configuration operation

<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveClusterDatastoreConfigurationResponse> <returnval> <Datastore>datastore-11</Datastore> <propSet> <name>summary</name> <DatastoreSummary> <Datastore>datastore-11</Datastore> <name>dev15 disk1</name> <url>sanfs://vmfs_uuid:470e81f0-32b2d06a-a25c-0019b9e1c5fe/</url> disk2</name> <url>sanfs://vmfs_uuid:478d1b24-552c354d-c670-0019b9e1c5fe/</url> Cluster TEST</cluster-compute-resource> </RetrieveClusterDatastoreConfigurationResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Cluster_Datastore_Configuration operation Element accessible Definition The connectivity status of this datastore A value of false, meaning the datastore is not accessible and the this datastore capacity and free space properties cannot be validated. Maximum capacity of this datastore, in bytes Available space of this datastore, in bytes
capacity freeSpace
multipleHostAccess If it set to true, means more than one host in the datacenter has been configured with access to the datastore name The name of the datastore
type
Type of file system volume, such as VMFS or NFS
Request and response for the Retrieve_Clusters operation

This operation retrieves all known clusters and configuration on a VMware VirtualCenter. The following table describes the elements for this request. Adapter request elements for Retrieve_Clusters operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Cluster. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Clusters. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters user-name Contains the data types and elements of the operation The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
No No
password
The following code sample shows a sample adapter request for the Retrieve_Clusters operation. Sample adapter request for Retrieve_Clusters operation
<vmware-infrastructure-request> <operation-type>Cluster</operation-type> <operation-name>Retrieve_Clusters</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters></parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Clusters operation. Sample adapter response for Retrieve_Clusters operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveClustersResponse> <returnval> <ClusterComputeResource>Testcluster</ClusterComputeResource> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>configuration</name> <ClusterConfigInfo> <dasConfig> <enabled>false</enabled> <failoverLevel>1</failoverLevel> <admissionControlEnabled>true</admissionControlEnabled> </dasConfig> <drsConfig> <enabled>true</enabled> <defaultVmBehavior>fullyAutomated</defaultVmBehavior> <vmotionRate>3</vmotionRate> </drsConfig> </ClusterConfigInfo> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>datastore</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet>
<propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.domain-c1500</key> <ClusterComputeResource>Testcluster</ClusterComputeResource> <Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.109375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>drsRecommendation</name> <ArrayOfClusterDrsRecommendation></ArrayOfClusterDrsRecommendation> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>host</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>migrationHistory</name> <ArrayOfClusterDrsMigration></ArrayOfClusterDrsMigration> </propSet> <propSet> <name>name</name> <val>Testcluster</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>host</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission></ArrayOfPermission> </propSet> <propSet> <name>recentTask</name>
<ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>resourcePool</name> <ResourcePool>resgroup-1502</ResourcePool> </propSet> <propSet> <name>summary</name> <ClusterComputeResourceSummary> <totalCpu>0</totalCpu> <totalMemory>0</totalMemory> <numCpuCores>0</numCpuCores> <numCpuThreads>0</numCpuThreads> <effectiveCpu>0</effectiveCpu> <effectiveMemory>0</effectiveMemory> <numHosts>0</numHosts> <numEffectiveHosts>0</numEffectiveHosts> <overallStatus>green</overallStatus> <currentFailoverLevel>-1</currentFailoverLevel> <numVmotions>0</numVmotions> </ClusterComputeResourceSummary> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> </returnval> <returnval> <ClusterComputeResource>R1</ClusterComputeResource> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>configuration</name> <ClusterConfigInfo> <dasConfig> <enabled>false</enabled> <failoverLevel>1</failoverLevel> <admissionControlEnabled>true</admissionControlEnabled> </dasConfig> <drsConfig> <enabled>true</enabled> <defaultVmBehavior>fullyAutomated</defaultVmBehavior> <vmotionRate>3</vmotionRate> </drsConfig> </ClusterConfigInfo> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet>
<propSet> <name>datastore</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-5.domain-c4676</key> <ClusterComputeResource>R1</ClusterComputeResource> <Alarm>alarm-5</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.125Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>drsRecommendation</name> <ArrayOfClusterDrsRecommendation></ArrayOfClusterDrsRecommendation> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>host</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>migrationHistory</name> <ArrayOfClusterDrsMigration></ArrayOfClusterDrsMigration> </propSet> <propSet> <name>name</name> <val>Ranga</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>host</Folder> </propSet> <propSet> <name>permission</name>
<ArrayOfPermission></ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>resourcePool</name> <ResourcePool>resgroup-4678</ResourcePool> </propSet> <propSet> <name>summary</name> <ClusterComputeResourceSummary> <totalCpu>0</totalCpu> <totalMemory>0</totalMemory> <numCpuCores>0</numCpuCores> <numCpuThreads>0</numCpuThreads> <effectiveCpu>0</effectiveCpu> <effectiveMemory>0</effectiveMemory> <numHosts>0</numHosts> <numEffectiveHosts>0</numEffectiveHosts> <overallStatus>green</overallStatus> <currentFailoverLevel>-1</currentFailoverLevel> <numVmotions>0</numVmotions> </ClusterComputeResourceSummary> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> </returnval> <returnval> <ClusterComputeResource>DRS Cluster TEST</ClusterComputeResource> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>configuration</name> <ClusterConfigInfo> <dasConfig> <enabled>false</enabled> <failoverLevel>1</failoverLevel> <admissionControlEnabled>true</admissionControlEnabled> </dasConfig> <drsConfig> <enabled>true</enabled> <defaultVmBehavior>manual</defaultVmBehavior> <vmotionRate>3</vmotionRate> </drsConfig> </ClusterConfigInfo> </propSet>
<propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>datastore</name> <ArrayOfManagedObjectReference> <Datastore>datastore-11</Datastore> <Datastore>datastore-13</Datastore> <Datastore>datastore-15</Datastore> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.domain-c614</key> <ClusterComputeResource>DRS Cluster TEST</ClusterComputeResource> <Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.09375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>drsRecommendation</name> <ArrayOfClusterDrsRecommendation></ArrayOfClusterDrsRecommendation> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>environmentBrowser</name> <EnvironmentBrowser>envbrowser-614</EnvironmentBrowser> </propSet> <propSet> <name>host</name> <ArrayOfManagedObjectReference> <HostSystem>dev1.bmc.com</HostSystem> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>migrationHistory</name> <ArrayOfClusterDrsMigration></ArrayOfClusterDrsMigration> </propSet> <propSet> <name>name</name> <val>DRS Cluster TEST</val> </propSet>
<propSet> <name>network</name> <ArrayOfManagedObjectReference> <Network>network-3570</Network> <Network>network-17</Network> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>green</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>host</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <ClusterComputeResource>DRS Cluster TEST</ClusterComputeResource> <principal>qauser</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> </ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>resourcePool</name> <ResourcePool>resgroup-616</ResourcePool> </propSet> <propSet> <name>summary</name> <ClusterComputeResourceSummary> <totalCpu>14896</totalCpu> <totalMemory>34359377920</totalMemory> <numCpuCores>8</numCpuCores> <numCpuThreads>8</numCpuThreads> <effectiveCpu>14430</effectiveCpu> <effectiveMemory>29922</effectiveMemory> <numHosts>1</numHosts> <numEffectiveHosts>1</numEffectiveHosts> <overallStatus>green</overallStatus> <currentFailoverLevel>-1</currentFailoverLevel> <numVmotions>0</numVmotions> </ClusterComputeResourceSummary> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet>
</returnval> </RetrieveClustersResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Clusters operation Element configuration Definition Configuration of the VMware High Availability service and VMware DRS.
drsRecommendation If DRS is enabled, this returns the set of recommended migrations from the DRS module. Even if DRS is enabled, the current set of recommendations may be empty, since there may be no recommended migrations at this time. If DRS is not enabled, always returns an empty list. migrationHistory datastore host network The set of migration decisions that have recently been performed This list is populated only when DRS is in automatic mode A collection of references to the datastore objects in this datacenter available in the ComputeResource List of hosts that are part of this compute resource If the compute resource is a standalone type, this list contains just one element. T The subset of network objects available in the datacenter that is available in this ComputeResource. This property is computed as the aggregate set of networks available from all the hosts that are part of this compute resource. Reference to root resource pool
resourcePool
environmentBrowser The environment browser object that identifies the environments that are supported on this compute resource. summary Basic runtime information about a compute resource This information is used on summary screens and in list views.
Request and response for the Update_Cluster_DRS_Configuration operation

This operation enables you to update the Cluster DRS ((Distributed Resource Scheduler) configuration. You can also use this operation to manage DRS settings at the virtual machine level. The following table describes the adapter request elements for the Update_Cluster_DRS_Configuration operation: Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Cluster. Defines the name of the operation For this operation, the value of operation-name is Update_Cluster_DRS_Configuration. Required Yes Yes
soap-url
Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note: If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
No
transport
Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note: If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
parameters
Yes Yes
cluster-compute-resource The name of the cluster whose DRS configuration needs to be updated Valid value: Any string
drs-config
Specifies the DRS configuration This element includes the default settings for virtual machines. Valid format: <drs-config> <enabled></enabled> <enable-vm-behavior-overrides></enable-vm-behavior-overrides> <default-vm-behavior></default-vm-behavior> </drs-config> <enabled>: Flag that specifies whether the service is enabled <enable-vm-behavior-overrides>: Flag that indicates whether the DRS behavior overrides for individual virtual machines are enabled. The default value is false. <default-vm-behavior>: Specifies the cluster-wide default DRS behavior for virtual machines. Valid values are: fullyAutomated - Specifies that the VirtualCenter should automate both the migration of the virtual machines and their placement on a host in the powered-on state manual - Specifies that the VirtualCenter should generate recommendations for virtual machine migration and for placement with a host, but should not implement the recommendation automatically partialAutomated - Specifies that VirtualCenter should generate recommendations for virtual machine migration and for placement with a host, but should automatically implement only the placement at power on
No
drs-vm-config-spec
Specifies the DRS configuration for individual virtual machines The entries in this array override the cluster default settings. Valid format: <drs-vm-config-spec> <operation></operation> <info> <virtual-machine></virtual-machine> <enabled></enabled> <behavior></behavior> </info> </drs-vm-config-spec> <operation>: Specifies the type of operation being performed. This element is applicable only if the virtual machine specific DRS settings needs to be updated. Valid values are: add - add a configuration for the virtual machine, overwriting the existing configuration if it exists edit: incrementally update the existing configuration; an existing configuration must exist. In the context of updating DRS settings of a virtual machine, this means that 'edit' can only be specified when the 'Automation Level' of virtual machine is set to a value other than "(Default) Manual". <virtual-machine>: Specifies the virtual machine whose DRS configuration needs to be updated <enabled>: Indicates whether the VirtualCenter is allowed to perform any DRS migration or initial placement recommendations for this virtual machine. If this flag is false, the virtual machine is effectively excluded from DRS. If no individual DRS specification exists for a virtual machine, this propert defaults to true. <behavior>: Specifies the particular DRS behavior for this virtual machine. Valid values are: fullyAutomated: Specifies that the VirtualCenter should automate both the migration of virtual machines and their placement with a host in the powered-on state manual: Specifies that the VirtualCenter should generate recommendations for virtual machine migration and for placement with a host, but should not implement the recommendations automatically. partiallyAutomated: Specifies that the VirtualCenter should generate recommendations for virtual machine migration and for placement with a host, but should automatically implement only the placement at power on.
No
modify
If this element is set to true, an unset property has no effect on the existing property value in the cluster configuration of the server. If this element is set to false, the cluster configuration reverts to the default values, and the new configuration values are applied later.
Yes
user-name
The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
No
password
The following code sample shows a sample adapter request for the Update_Cluster_DRS_Configuration operation. Sample adapter request for the Update_Cluster_DRS_Configuration operation
<vmware-infrastructure-request> <operation-type>Cluster</operation-type> <operation-name>Update_Cluster_DRS_Configuration</operation-name> <vmware-infrastructure-request> <operation-type>Cluster</operation-type> <operation-name>Update_Cluster_DRS_Configuration</operation-name> <parameters> <cluster-compute-resource>Test Cluster</cluster-compute-resource> <spec> <drs-config> <enabled>true</enabled> <enable-vm-behavior-overrides>true</enable-vm-behavior-overrides> <default-vm-behavior>manual</default-vm-behavior> </drs-config> <drs-vm-config-spec> <operation>add</operation> <info> <virtual-machine>TestLinuxOne</virtual-machine> <enabled>true</enabled> <behavior>fullyAutomated</behavior> </info> </drs-vm-config-spec> </spec> <modify>true</modify> </parameters> </vmware-infrastructure-request> </vmware-infrastructure-request>
The following code sample shows the response for the sample Update_Cluster_DRS_Configuration operation. Sample adapter response for the Update_Cluster_DRS_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ReconfigureComputeResource_TaskResponse> <Task>task-5162</Task> </ReconfigureComputeResource_TaskResponse> </vmware-infrastructure-response>
Adapter requests and responses for Datacenter operations

The following topic details the adapter request and response for the Retrieve Datacenter operation.
Request and response for the Retrieve_Datacenters operation
Request and response for the Retrieve_Datacenters operation

This operation retrieves the known datacenters and configuration on a VMware VirtualCenter. The following table describes the elements for this request. Adapter request elements for Retrieve_Datacenters operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Datacenter. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Datacenters. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters user-name Contains the data types and elements of the operation The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
No No
password
Conditional. Required if user-name is provided.
The following code sample shows a sample adapter request for the Retrieve_Datacenters operation. Sample adapter request for Retrieve_Datacenters operation
<vmware-infrastructure-request> <operation-type>Datacenter</operation-type> <operation-name>Retrieve_Datacenters</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters></parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Datacenters operation. Sample adapter response for Retrieve_Datacenters operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveDatacentersResponse> <returnval> <Datacenter>datacenter-2</Datacenter> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>datastore</name> <ArrayOfManagedObjectReference> <Datastore>dev15 disk1</Datastore> <Datastore>dev15 disk2</Datastore> <Datastore>dev15 disk3</Datastore> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.datacenter-2</key> <Datacenter>datacenter-2</Datacenter>
<Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.09375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>hostFolder</name> <Folder>host</Folder> </propSet> <propSet> <name>name</name> <val>ABC_DEV</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference> <Network>DummyNetwork</Network> <Network>VM Network</Network> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>Datacenters</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <Datacenter>datacenter-2</Datacenter> <principal>abc</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> <Permission> <Datacenter>datacenter-2</Datacenter> <principal>user1</principal> <group>false</group> <roleId>-2</roleId> <propagate>true</propagate> </Permission>
</ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> <propSet> <name>vmFolder</name> <Folder>vm</Folder> </propSet> </returnval> <returnval> <Datacenter>datacenter-60</Datacenter> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>datastore</name> <ArrayOfManagedObjectReference> <Datastore>storage1</Datastore> <Datastore>storage2</Datastore> <Datastore>storage3</Datastore> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.datacenter-60</key> <Datacenter>datacenter-60</Datacenter> <Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.109375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt>
<int>1</int> </ArrayOfInt> </propSet> <propSet> <name>hostFolder</name> <Folder>host</Folder> </propSet> <propSet> <name>name</name> <val>ABC_DEV2</val> </propSet> <propSet> <name>network</name> <ArrayOfManagedObjectReference> <Network>VM Network</Network> <Network>Virtual Machine Network</Network> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>Datacenters</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <Datacenter>datacenter-60</Datacenter> <principal>qauser</principal> <group>false</group> <roleId>2</roleId> <propagate>true</propagate> </Permission> <Permission> <Datacenter>datacenter-60</Datacenter> <principal>rba</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> <Permission> <Datacenter>datacenter-60</Datacenter> <principal>aouser</principal> <group>false</group> <roleId>-2</roleId> <propagate>true</propagate> </Permission> </ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet>
<propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> <propSet> <name>vmFolder</name> <Folder>vm</Folder> </propSet>
</returnval> </RetrieveDatacentersResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Datacenters operation Element datastore hostFolder network vmFolder Definition A collection of references to the datastore objects available in the datacenter The folder hierarchy that contains the compute resources, including hosts and clusters, for the datacenter A collection of references to the network objects available in this datacenter The folder hierarchy that contains the virtual machines and templates for the datacenter
effectiveRole Access rights of the current session to the datacenter permission List of permissions defined for the datacenter
overallStatus The general health of the datacenter. The value combines the status of all the alarms attached to a datacenter. If any of the alarms have a gray status, the overall status of the datacenter is gray. If any of the alarms have a red status, the overall status of the datacenter is red. If any of the alarms have a yellow status, the overall status of the datacenter is yellow. Otherwise, the overall status of the datacenter is green.
Adapter requests and responses for Folder operations

The following topics illustrate the request and response for the Folder operations.
Request and response for the Create_Folder operation Request and response for the Retrieve_Folders operation Request and response for the Destroy_Folder operation
Request and response for the Create_Folder operation

This operation enables you to create a sub-folder within a folder, with the specified name. The following table describes the elements for this request. Adapter request elements for Create_Folder operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Folder. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Create_Folder.
soap-url
No
transport
No
parameters parent-folder
Contains the data types and elements of the operation Specifies the name of the parent folder within which you want to create a sub-folder This element can contain only String values. Specifies the name for the new folder that you want to create This element can contain only String values. You must specify a non-empty string of less than or equal to 80 characters. The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
Yes Yes
name
Yes
user-name
No
password
The following code sample shows a sample adapter request for the Create_Folder operation. Sample adapter request for the Create_Folder operation
<vmware-infrastructure-request> <operation-type>Folder</operation-type> <operation-name>Create_Folder</operation-name> <parameters> <parent-folder>Test</parent-folder> <name>TestFolder1</name> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Create_Folder operation. Sample adapter response for the Create_Folder operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateFolderResponse> <Folder>group-v7343</Folder> </CreateFolderResponse> </vmware-infrastructure-response>
Request and response for the Retrieve_Folders operation

This operation retrieves all the folders and the corresponding configuration on a VMware VirtualCenter, filtered by datacenter. The following table describes the elements for this request. Adapter request elements for Retrieve_Folders operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Folder. Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Folders. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation
No
No
datacenter
Specifies the name of the datacenter The operation retrieves all the folders and the corresponding configuration on a VMware VirtualCenter running on the specified datacenter. If the datacenter element is not specified, the operation retrieves all the folders existing on the VMware VirtualCenter. Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Folders operation. Sample adapter request for Retrieve_Folders operation
<vmware-infrastructure-request> <operation-type>Folder</operation-type> <operation-name>Retrieve_Folders</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <datacenter>DEV1</datacenter> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Folders operation. Sample adapter response for Retrieve_Folders operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveFoldersResponse> <returnval> <Folder>host</Folder> <propSet> <name>childEntity</name> <ArrayOfManagedObjectReference> <ClusterComputeResource>domain-c4676</ClusterComputeResource> <ClusterComputeResource>domain-c614</ClusterComputeResource> <ComputeResource>domain-s4697</ComputeResource> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>childType</name>
<ArrayOfString> <string>Folder</string> <string>ComputeResource</string> </ArrayOfString> </propSet> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-1.group-h4</key> <Folder>host</Folder> <Alarm>alarm-1</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.09375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>name</name> <val>host</val> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Datacenter>datacenter-2</Datacenter> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <Datacenter>datacenter-2</Datacenter>
<principal>user1</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> <Permission> <Datacenter>datacenter-2</Datacenter> <principal>user2</principal> <group>false</group> <roleId>-2</roleId> <propagate>true</propagate> </Permission> </ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> </returnval> <returnval> <Folder>Discovered Virtual Machine</Folder> <propSet> <name>childEntity</name> <ArrayOfManagedObjectReference> <VirtualMachine>DEV_VM_ITSM703_FlightDeck</VirtualMachine> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>childType</name> <ArrayOfString> <string>Folder</string> <string>VirtualMachine</string> </ArrayOfString> </propSet> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>declaredAlarmState</name> <ArrayOfAlarmState> <AlarmState> <key>alarm-4.group-v1853</key> <Folder>Discovered Virtual Machine</Folder>
<Alarm>alarm-4</Alarm> <overallStatus>gray</overallStatus> <time>2009-11-17T06:48:19.109375Z</time> </AlarmState> </ArrayOfAlarmState> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>name</name> <val>Discovered Virtual Machine</val> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Folder>vm</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission></ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> </returnval> <returnval> <Folder>vm</Folder> <propSet> <name>childEntity</name> <ArrayOfManagedObjectReference> <Folder>Discovered Virtual Machine</Folder> <Folder>Test</Folder> <VirtualMachine>DEV_VM_BLOM745_Module</VirtualMachine> <VirtualMachine>DEV_VM_CDPBLOM745_Module</VirtualMachine> <VirtualMachine>VISClone1</VirtualMachine> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>childType</name> <ArrayOfString>
<string>Folder</string> <string>VirtualMachine</string> </ArrayOfString> </propSet> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>name</name> <val>vm</val> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>parent</name> <Datacenter>datacenter-2</Datacenter> </propSet> <propSet> <name>permission</name> <ArrayOfPermission> <Permission> <Datacenter>datacenter-2</Datacenter> <principal>user1</principal> <group>false</group> <roleId>1</roleId> <propagate>true</propagate> </Permission> <Permission> <Datacenter>datacenter-2</Datacenter> <principal>user2</principal> <group>false</group> <roleId>-2</roleId> <propagate>true</propagate> </Permission> </ArrayOfPermission>
</propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet> </returnval> <returnval> <Folder>Test</Folder> <propSet> <name>childEntity</name> <ArrayOfManagedObjectReference> <VirtualMachine>Det3</VirtualMachine> <VirtualMachine>TestVM3</VirtualMachine> </ArrayOfManagedObjectReference> </propSet> <propSet> <name>childType</name> <ArrayOfString> <string>Folder</string> <string>VirtualMachine</string> </ArrayOfString> </propSet> <propSet> <name>configIssue</name> <ArrayOfEvent></ArrayOfEvent> </propSet> <propSet> <name>configStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet> <propSet> <name>customValue</name> <ArrayOfCustomFieldValue></ArrayOfCustomFieldValue> </propSet> <propSet> <name>disabledMethod</name> <ArrayOfString></ArrayOfString> </propSet> <propSet> <name>effectiveRole</name> <ArrayOfInt> <int>1</int> </ArrayOfInt> </propSet> <propSet> <name>name</name> <val>Test</val> </propSet> <propSet> <name>overallStatus</name> <ManagedEntityStatus>gray</ManagedEntityStatus> </propSet>
<propSet> <name>parent</name> <Folder>vm</Folder> </propSet> <propSet> <name>permission</name> <ArrayOfPermission></ArrayOfPermission> </propSet> <propSet> <name>recentTask</name> <ArrayOfManagedObjectReference></ArrayOfManagedObjectReference> </propSet> <propSet> <name>triggeredAlarmState</name> <ArrayOfAlarmState></ArrayOfAlarmState> </propSet>
</returnval> </RetrieveFoldersResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Folders operations Element configIssue Definition Current configuration issues that have been detected for this entity Typically, these issues have already been logged as events. The entity stores these events as long as they are still current. The configStatus property provides an overall status based on these events. Indicates whether the system has detected a configuration issue involving the entity For example, it might have detected a duplicate IP address or MAC address, or a host in a cluster might be out of compliance. The meanings of the configStatus values are: red: A problem has been detected involving the entity. yellow: A problem is about to occur or a transient condition has occurred (For example, reconfigure fail-over policy). green: No configuration issues have been detecte gray: The configuration status of the entity is not being monitored A green status indicates only that a problem has not been detected; it is not a guarantee that the entity is problem-free.
configStatus
disabledMethod
List of operations that are disabled, given the current runtime state of the entity For example, a power-on operation always fails if a virtual machine is already powered on.
declaredAlarmState A set of alarm states for alarms that apply to this managed entity The set includes alarms defined on this entity and alarms inherited from the parent entity, or from any ancestors in the inventory hierarchy. Alarms are inherited if they can be triggered by this entity or its descendants. This set does not include alarms that are defined on descendants of the entity. effectiveRole permission overallStatus Access rights the current session has to the entity List of permissions defined for the entity General health of this managed entity The value combines the status of all the alarms attached to a managed entity. If any of the alarms has a gray status, the overall status of the managed entity is gray. If any of the alarms has a red status, the overall status of the managed entity is red. Ifany of the alarms has a yellow status, the overall status of the managed entity is yellow. Otherwise, the overall status of the managed entity is green.
Request and response for the Destroy_Folder operation

This operation enables you to destroy the specified folder object by deleting the contents of the folder and removing the folder from the parent folder, if the parent folder exists. The following table describes the elements for this request. Adapter request elements for the Destroy_Folder operation
Definition Defines the type of operation For this operation, the value of operation-type is Folder.
Required Yes Yes No
operation-name Defines the name of operation For this operation, the value of operation-name is Destroy_Folder. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters folder Contains the data types and elements of the operation Specifies the name of the folder that you want to destroy All the objects and sub-folders in the specified folder are removed. Valid value: String The name of the user If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name
No
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Destroy_Folder operation. Sample adapter request for the Destroy_Folder operation
<vmware-infrastructure-request> <operation-type>Folder</operation-type> <operation-name>Destroy_Folder</operation-name> <parameters> <folder>Testfolder</folder> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Destroy_Folder operation. Sample adapter response for the Destroy_Folder operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <DestroyFolderResponse> <Task>task-10235</Task> </DestroyFolderResponse> </vmware-infrastructure-response>
Adapter requests and responses for Discovery operations

The following topics illustrate the requests and responses for the Discovery operations.
Request and response for the Retrieve_MOB_Reference_By_Display_Name operation Request and response for the Retrieve_Display_Name_By_MOB_Reference operation
Request and response for the Retrieve_MOB_Reference_By_Display_Name operation

This operation retrieves the Managed Object Reference for a VMware Infrastructure element using the display name. The following table describes the elements for this request. Adapter request elements for the Retrieve_MOB_Reference_By_Display_Name operation Element operation-type Definition Defines the type of operation For this operation, the value of operation-type is Discovery. Required Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_MOB_Reference_By_Display_Name.
soap-url
No
transport
parameters display-name
Contains the data types and elements of the operation Contains the display name of the VMware Infrastructure element whose Managed Object reference is to be retrieved Valid value: String Specifies the entity type of the infrastructure element whose MOB reference is to be retrieved Valid values: VirtualApp DistributedVirtualPortgroup Datacenter Folder VirtualMachine Datastore ClusterComputeResource ResourcePool Network HostSystem
Yes Yes
type
No
datacenter
Contains the name of the datacenter where the VMware Infrastructure element is located Valid value: String
No
user-name
The name of the user No If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name Conditional Required if user-name is provided
password
The following code sample shows a sample adapter request for the Retrieve_MOB_Reference_By_Display_Name operation. Sample adapter request for the Retrieve_MOB_Reference_By_Display_Name operation
<vmware-infrastructure-request> <operation-type>Discovery</operation-type> <operation-name>Retrieve_MOB_Reference_By_Display_Name</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <display-name>Demo1</display-name> <type>VirtualMachine</type> <datacenter></datacenter> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_MOB_Reference_By_Display_Name operation. Sample adapter response for the Retrieve_MOB_Reference_By_Display_Name operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveMOBReferenceByDisplayNameResponse> <mob-reference>vm-5741</mob-reference> </RetrieveMOBReferenceByDisplayNameResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_MOB_Reference_By_Display_Name Element Definition
mob-reference Returns the ManagedObjectReference of the specified entity object
Request and response for the Retrieve_Display_Name_By_MOB_Reference operation

This operation retrieves the display name, type, and the datacenter name of a VMware Infrastructure element using the Managed Object Reference of the element. The following table describes the elements for this request. Adapter request elements for the Retrieve_Display_Name_By_MOB_Reference operation Element Definition Required
operation-type
Defines the type of operation For this operation, the value of operation-type is Discovery.
Yes Yes
operation-name Defines the name of operation For this operation, the value of operation-name is Retrieve_Display_Name_By_MOB_Reference. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport
No
parameters mob-reference
Contains the data types and elements of the operation Contains the Managed Object reference of the VMware Infrastructure element whose display name, type, and datacenter name are to be retrieved Valid value: String
Yes Yes
user-name
The name of the user No If no user name is specified, the request executes with the user name specified in the adapter configuration. The password corresponding to the specified user name Conditional Required if user-name is provided
password
The following code sample shows a sample adapter request for the Retrieve_Display_Name_By_MOB_Reference operation. Sample adapter request for the Retrieve_Display_Name_By_MOB_Reference operation
<vmware-infrastructure-request> <operation-type>Discovery</operation-type> <operation-name>Retrieve_Display_Name_By_MOB_Reference</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <mob-reference>testvm-571</mob-reference> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Display_Name_By_MOB_Reference operation. Sample adapter response for the Retrieve_Display_Name_By_MOB_Reference operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveDisplayNameByMOBReferenceResponse> <display-name>Demo1</display-name> <type>VirtualMachine</type> <datacenter>ABC_DEV</datacenter> </RetrieveDisplayNameByMOBReferenceResponse> </vmware-infrastructure-response>
The following table describes the response elements. Adapter response elements for the Retrieve_Display_Name_By_MOB_Reference Element Definition
display-name Returns the display name of given mob reference along with the entity type and its associated datacenter.
Adapter requests and responses for the Resource Pool operation

The following topic illustrates the adapter request and response for the Resource Pool operation.
Request and response for the Retrieve_Resource_Pool_Children operation

This operation enables you to retrieve a list of all children resource pools associated with the specified resource pool. The following table describes the elements for this request. Adapter request elements for the Retrieve_Resource_Pool_Children operation Element Definition Required
operation-type
Defines the type of the operation For this operation, the value of operation-type is ResourcePool.
Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Retrieve_Resource_Pool_Children. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters resource-pool Contains the data types and elements of the operation Specifies the name of the resource pool for which you want to retrieve a list of children resource pools Valid value: String The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
No
Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Retrieve_Resource_Pool_Children operation. Sample adapter request for the Retrieve_Resource_Pool_Children operation
<vmware-infrastructure-request> <operation-type>ResourcePool</operation-type> <operation-name>Retrieve_Resource_Pool_Children</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <resource-pool>/abc/host/TestCluster/Resources</resource-pool> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Retrieve_Resource_Pool_Children operation. Sample adapter response for the Retrieve_Resource_Pool_Children operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <RetrieveResourcePoolChildrenResponse> <returnval> <ResourcePool>resgroup-1834</ResourcePool> <propSet> <name>name</name> <val>Resources</val> </propSet> <propSet> <name>parent</name> <ClusterComputeResource>domain-c1183</ClusterComputeResource> </propSet> <propSet> <name>resourcePool</name> <ArrayOfManagedObjectReference> <ResourcePool>resgroup-1188</ResourcePool> <ResourcePool>resgroup-1184</ResourcePool> <ResourcePool>resgroup-2110</ResourcePool> <ResourcePool>resgroup-2121</ResourcePool> </ArrayOfManagedObjectReference> </propSet> </returnval> <returnval> <ResourcePool>resgroup-1188</ResourcePool> <propSet> <name>name</name> <val>0882004552-BMCDevOrgvDC</val> </propSet> <propSet> <name>parent</name> <ResourcePool>resgroup-1184</ResourcePool> </propSet> <propSet>
<name>resourcePool</name> <ArrayOfManagedObjectReference /> </propSet> </returnval> <returnval> <ResourcePool>resgroup-2110</ResourcePool> <propSet> <name>name</name> <val>TestRP</val> </propSet> <propSet> <name>parent</name> <ResourcePool>resgroup-1186</ResourcePool> </propSet> <propSet> <name>resourcePool</name> <ArrayOfManagedObjectReference> <ResourcePool>resgroup-2121</ResourcePool> </ArrayOfManagedObjectReference> </propSet>
</returnval> </RetrieveResourcePoolChildrenResponse> </vmware-infrastructure-response>
Adapter requests and responses for the Basic vApp operations

The following topics illustrate the requests and responses for the Basic vApp operations.
Request and response for the Power_On_VApp operation Request and response for the Power_Off_VApp operation Request and response for the Unregister_VApp operation
Request and response for the Power_On_VApp operation

The Power_On_VApp operation starts the specified vApp. The virtual machines (or sub vApps) associated with the vApp are started in the order specified in the vApp configuration. The following table describes the elements for this request. Adapter request elements for the Power_On_VApp operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_VApp. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Power_On_VApp. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.
No
parameters virtual-app user-name
Contains the data types and elements of the operation Specifies the name of the vApp that you want to power on Valid value: String The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Power_On_VApp operation. Sample adapter request for the Power_On_VApp operation
<vmware-infrastructure-request> <operation-type>Basic_VApp</operation-type> <operation-name>Power_On_VApp</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-app>TestVApp</virtual-app> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Power_On_VApp operation. Sample adapter response for the Power_On_VApp operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <PowerOnVApp_TaskResponse> <Task>task-9300</Task> </PowerOnVApp_TaskResponse> </vmware-infrastructure-response>
Request and response for the Power_Off_VApp operation

This operation stops the specified vApp. You can chose to stop the virtual machines (or child vApps) associated with the vApp in the order specified in the vApp configuration, by setting the <force> element to false. If the <force> element is set to true, all virtual machines are stopped in no specific order, regardless of the auto-start configuration for the vApp. The following table describes the elements for this request.
Adapter request elements for the Power_Off_VApp operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_VApp. Required Yes Yes No
operation-name Defines the name of the operation For this operation, the value of operation-name is Power_Off_VApp. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters virtual-app force Contains the data types and elements of the operation Specifies the name of the vApp that you want to stop Specifies whether the shutdown order of the vApp is executed Valid values: true, false If the force element is set to true, the shutdown order in the vApp is executed. If the force element is set to false, the virtual machines in the vApp are shut down regardless of the shutdown order. The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
Yes Yes Yes
user-name
No
password
The following code sample shows a sample adapter request for the Power_Off_VApp operation. Sample adapter request for the Power_Off_VApp operation
<vmware-infrastructure-request> <operation-type>Basic_VApp</operation-type> <operation-name>Power_Off_VApp</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-app>TestVApp</virtual-app> <force>false</force> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Power_Off_VApp operation. Sample adapter response for the Power_Off_VApp operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <PowerOffVApp_TaskResponse> <Task>task-9303</Task> </PowerOffVApp_TaskResponse> </vmware-infrastructure-response>
Request and response for the Unregister_VApp operation

This operation removes the specified vApp from the inventory without removing any of the associated files on disk for the virtual machines in the vApp. All high-level information stored with the VMware ESX Server or VMware Virtual Center is removed, including information about the configuration, statistics, permissions, and alarms for the vApp. The following code sample describes the elements for this request. Adapter request elements for the Unregister_VApp operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Basic_VApp. Required Yes Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Unregister_VApp.
soap-url
No
transport
No
parameters virtual-app user-name
Contains the data types and elements of the operation Specifies the name of the vApp that you want to unregister Valid value: String The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes Yes No
password
The following code sample shows a sample adapter request for the Unregister_VApp operation. Sample adapter request for the Unregister_VApp operation
<vmware-infrastructure-request> <operation-type>Basic_VApp</operation-type> <operation-name>Unregister_VApp</operation-name> <soap-url></soap-url> <transport></transport> <user-name></user-name> <password></password> <parameters> <virtual-app>TestVApp</virtual-app> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Unregister_VApp operation. Sample adapter response for the Unregister_VApp operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <unregisterVApp_TaskResponse> <Task>task-9306</Task> </unregisterVApp_TaskResponse> </vmware-infrastructure-response>
Adapter requests and responses for the VApp Configuration operations

The following topics illustrate the requests and responses for the VApp Configuration operations.
Request and response for the Export_VApp_As_OVF_Template operation Request and response for the Import_OVF_Template_As_VApp operation Request and response for the Create VApp operation Request and response for the Clone_VApp operation Request and response for the Update_VApp_Configuration operation
Request and response for the Export_VApp_As_OVF_Template operation

This operation exports the specified vApp as an Open Virtualization Format (OVF) template and also downloads the files associated with the vApp entity. Note The vApp that you want to export as an OVF template must not contain child resource pools.
The following table describes the elements for this request. Adapter request elements for the Export_VApp_As_OVF_Template operation Element operation-type operation-name Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VApp. Defines the name of the operation For this operation, the value of operation-name is Export_VApp_As_OVF_Template. Required Yes Yes
soap-url
No
transport
No
parameters virtual-app
Contains the data types and elements of the operation Specifies the name of the vApp that you want to export as an OVF template Valid value: String
Yes Yes
ovf-download-directory Specifies the directory on the local BMC Atrium Orchestrator peer where the virtual appliance OVF descriptor and other entity files are exported to Valid value: String cdp Contains the list of parameters required for generating the OVF descriptor Sample format:
<cdp> <name></name> <description></description> </cdp>
Yes
No
The <name> element specifies the OVF ID to use for the top-level OVF entity. If the OVF ID is not set, the entity's product name is used. If the product name is not available, the VMware Infrastructure entity name is used. Valid value: String The <description> element specifies the contents of the annotation section of the top-level OVF Entity. If the description is not set, any existing annotation on the entity is left unchanged. Valid value: String
user-name
The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
No
password
The following code sample shows a sample adapter request for the Export_VApp_As_OVF_Template operation. Sample adapter request for the Export_VApp_As_OVF_Template operation
<vmware-infrastructure-request> <operation-type>Configure_VApp</operation-type> <operation-name>Export_VApp_As_OVF_Template</operation-name> <parameters> <virtual-app>vApptest</virtual-app> <ovf-download-directory>/home/test</ovf-download-directory> <cdp> <name>vApptest_OVF</name> <description>OVF Format of vApptest</description> </cdp> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Export_VApp_As_OVF_Template operation. Sample adapter response for the Export_VApp_As_OVF_Template operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ExportVAppResponse> <ovf-download-directory>/home/test</ovf-download-directory> </ExportVAppResponse> </vmware-infrastructure-response>
Request and response for the Import_OVF_Template_As_VApp operation

This operation creates a new VApp in the resource pool based on the specified OVF descriptor. This operation also uploads the files that are associated with the VApp entity, such as the disk files. The following table describes the elements for this request. Adapter request elements for the Import_OVF_Template_As_VApp operation Element Definition Required
operation-type
Defines the type of the operation For this operation, the value of operation-type is Configure_VApp. Defines the name of the operation For this operation, the value of operation-name is Import_OVF_Template_As_VApp. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http:// hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
Yes
operation-name
Yes
soap-url
No
transport
No
parameters datacenter
Contains the data types and elements of the operation Specifies the datacenter where you want to import the virtual appliance Valid value: String Specifies the name of the new vApp that you want to create by importing the OVF template Specifies the ESX host on which the new vApp will run
Yes Yes
virtual-app host-system
Yes No If the host-system is not specified, you must specify either the parent-virtual-app or the resource-pool element. Yes
datastore
Specifies the datastore on which to create the inventory objects associated with the new vApp
parent-virtual-app Specifies the parent vApp under which the vApp is to be imported
No If you specify this element, the values in the resource-pool and folder elements are ignored. If you do not specify this element, you must specify either the host-system or resource-pool element. No If the resource-pool element is not specified, you must specify either the host-system or parent-virtual-app element. No
resource-pool
Specifies the resource pool where the vApp is to be added. The value in this element must be a valid vApp name. Valid value: String Specifies the folder to which the vApp will be attached Valid value: String If you do not specify this element, the default 'vm' folder is used.
folder
ovf-descriptor-file Contains the canonical path for the OVF descriptor file Valid value: String user-name The name of the user If no user name is specified, the request is executed with user specified in the configuration. The password corresponding to the specified user name
Yes No
password
The following code sample shows a sample adapter request for the Import_OVF_Template_As_VApp operation. Sample adapter request for the Import_OVF_Template_As_VApp operation
<vmware-infrastructure-request> <operation-type>Configure_VApp</operation-type> <operation-name>Import_OVF_Template_As_VApp</operation-name> <parameters> <datacenter>datacenter1</datacenter> <virtual-app>vApptest</virtual-app> <host-system>10.118.148.119</host-system> <datastore>Storage1</datastore> <resource-pool>/BMCOne/host/BMC Cluster/Resources/TestRP</resource-pool> <folder>/BMCOne/vm/TestFolder</folder> <ovf-descriptor-file>/home/Test/Test.ovf</ovf-descriptor-file> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Import_OVF_Template_As_VApp operation. Sample adapter response for the Import_OVF_Template_As_VApp operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <ImportVAppResponse> <virtual-app>vApptest</virtual-app> </ImportVAppResponse> </vmware-infrastructure-response>
Request and response for the Create VApp operation

This operation creates a vApp container with the specified name. The following table describes the elements for this request. Adapter request elements for the Create_VApp operation Element operation-type operation-name soap-url Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VApp. Defines the name of the operation For this operation, the value of operation-name is Create_VApp. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters Contains the data types and elements of the operation Yes No Required Yes Yes No
datacenter
The name of the datacenter where the inventory objects for the vApp are created Valid value: String
Conditional Required only i <resource-pool <cluster-compu elements are se <parent-virtual<folder> eleme set Yes
name resource-pool
Specifies the name of the vApp container in the inventory Valid value: String Specifies the resource pool where the new vApp is to be added This value is ignored if the <parent-virtual-app> element is specified.
Conditional If <cluster-compu and parent-virtu not specified, th is required.
parent-virtual-app
The parent vApp under which the specified vApp will be created Valid value: String If this element is specified, the <resource-pool> and <folder> elements are ignored.
No If this element i specified, you m either the <cluster-compu or <resource-po element.
cluster-compute-resource Specifies the cluster compute resource in which to create the specified vApp
Yes This element is the <parent-virt element is spec No
folder
Specifies the folder to associate the vApp with Valid value: String
resource-spec
Specifies the resource configuration for the vApp container Sample format:
<resource-spec> <cpu-allocation> <expandable-reservation></expandable-reservation> <limit></limit> <reservation><reservation> <shares> <shares></shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <expandable-reservation></expandable-reservation> <limit></limit> <reservation></reservation> <shares> <shares></shares> <level></level> </shares> </memory-allocation> </resource-spec>
Yes
For more information about the <cpu-allocation> and <memory-allocation> elements, see cpu-allocation and memory-allocation. config-spec Contains metadata specific to the vApp Sample format:
<config-spec> <annotation>testvApp</annotation> </config-spec>
No
annotation: Specifies the description of the virtual appliance Valid value: String user-name The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name No
password
Conditional Required if the element is prov
The following code sample shows a sample adapter request for the Create_VApp operation. Sample adapter request for the Create_VApp operation
<vmware-infrastructure-request> <operation-type>Configure_VApp</operation-type> <operation-name>Create_VApp</operation-name> <parameters> <datacenter>datacenterOne</datacenter> <name>TestVapp</name> <resource-pool>ABC</resource-pool> <parent-virtual-app>vApp One</parent-virtual-app> <cluster-compute-resource>test_cluster</cluster-compute-resource> <folder>testfolder</folder> <resource-spec> <cpu-allocation> <expandable-reservation>true</expandable-reservation> <limit>3210</limit> <reservation>1234</reservation> <shares> <shares>12345</shares> <level>normal</level> </shares> </cpu-allocation> <memory-allocation> <expandable-reservation>true</expandable-reservation> <limit>432435</limit> <reservation>3412</reservation> <shares> <shares>654632</shares> <level>normal</level> </shares> </memory-allocation> </resource-spec> <config-spec> <annotation>This ia test VApp</annotation> </config-spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Create_VApp operation. Sample adapter response for the Create_VApp operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CreateVAppResponse> <VirtualApp>resgroup-v339</VirtualApp> </CreateVAppResponse> </vmware-infrastructure-response>
Request and response for the Clone_VApp operation
This operation creates a new vApp container from the specified vApp. The following table describes the elements for this request. Adapter request elements for the Clone_VApp operation Element operation-type operation-name soap-url Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VApp. Defines the name of the operation For this operation, the value of operation-name is Clone_VApp. Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https:// hostname:port/sdk/vim Default value format for HTTP is http://hostname:port/sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application. transport Specifies the transport protocol for the message If the transport element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value is https-rpc. Valid values are https-rpc and http-rpc. Note If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled. parameters datacenter Contains the data types and elements of the operation The name of the datacenter where the inventory objects for the cloned vApp are created Valid value: String Yes No Required Yes Yes No
Conditional Required only i <resource-pool <cluster-compu elements are se <parent-virtual<folder> eleme set Yes
name resource-pool
Specifies the name of the vApp container in the inventory Valid value: String Specifies the resource pool where the cloned vApp will be added It can be a vApp name if you want to create the new vApp in another vApp. This value is ignored if the <parent-virtual-app> element is specified.
Conditional If <cluster-compu and <parent-vir are not specifie element is requ
parent-virtual-app
The parent vApp under which the cloned vApp will be created Valid value: String If this element is specified, the <resource-pool> and <folder> elements are ignored.
No If this element i specified, you m either the <cluster-compu or <resource-po element.
cluster-compute-resource Specifies the cluster compute resource in which to create the cloned vApp Valid value: String
Yes This element is the <parent-virt element is spec Yes Yes No Yes No No
virtual-app spec host location folder network-mapping
Specifies the vApp name from which the cloned vApp is to be created Valid value: String Contains parameters that specify how to clone the vApp Specifies the host on which the vApp will be created Specifies the location on which the vApp will be stored Valid value: String Specifies the folder to associate the vApp with Valid value: String Specifies the network mapping to map one network to another as part of the cloning process Sample format:
<network-mapping> <source>VM Network</source> <destination>VM Network2</destination> </network-mapping>
source: Specifies the source network of the cloned vApp Valid value: String destination: Specifies the destination network of the cloned vApp Valid value: String
resource-spec
Specifies the resource configuration for the vApp container Sample format:
<resource-spec> <cpu-allocation> <expandable-reservation></expandable-reservation> <limit></limit> <reservation><reservation> <shares> <shares></shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <expandable-reservation></expandable-reservation> <limit></limit> <reservation></reservation> <shares> <shares></shares> <level></level> </shares> </memory-allocation> </resource-spec>
No
For more information about the <cpu-allocation> and <memory-allocation> elements, see cpu-allocation and memory-allocation. user-name The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name No
password
Conditional Required if the element is prov
The following code sample shows a sample adapter request for the Clone_VApp operation. Sample adapter request for the Clone_VApp operation
<vmware-infrastructure-request> <operation-type>Configure_VApp</operation-type> <operation-name>Clone_VApp</operation-name> <parameters> <datacenter>datacenterOne</datacenter> <name>TestVapp</name> <resource-pool>Test_pool</resource-pool> <cluster-compute-resource>ABC Cluster</cluster-compute-resource> <virtual-app>TestVapp</virtual-app> <spec> <host>10.128.218.119</host> <location>Storage1</location> <folder>Test</folder> <network-mapping> <source>VM Network</source> <destination>VM Network 2</destination> </network-mapping> <resource-spec> <cpu-allocation> <expandable-reservation>true</expandable-reservation> <limit>1000</limit> <reservation>344</reservation> <shares> <shares>4000</shares> <level>custom</level> </shares> </cpu-allocation> <memory-allocation> <expandable-reservation>true</expandable-reservation> <limit>10000</limit> <reservation>1021</reservation> <shares> <shares>163840</shares> <level>custom</level> </shares> </memory-allocation> </resource-spec> </spec> </parameters> </vmware-infrastructure-request>
The following code sample shows the response for the sample Clone_VApp operation. Sample adapter response for the Clone_VApp operation
<adapter-response> <execution-duration>350</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <CloneVApp_TaskResponse> <Task>task-9212</Task> </CloneVApp_TaskResponse> </vmware-infrastructure-response>
Request and response for the Update_VApp_Configuration operation

This operation allows you to update the configuration of the specified vApp. The following table describes the elements for this request. Adapter request elements for the Update_VApp_Configuration operation Element operation-type Definition Defines the type of the operation For this operation, the value of operation-type is Configure_VApp. Required Yes
operation-name Defines the name of the operation For this operation, the value of operation-name is Update_VApp_Configuration. soap-url Specifies the URL for the remote SOAP service running on the VMware VirtualCenter If the soap-url element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration. The default value format for The default value format for HTTPS is https://hostname:port/sdk/vim Default value format for HTTP is http://hostname:port /sdk/vim Note If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.
Yes
No
transport
No
parameters resource-pool
Contains the data types and elements of the operation Specifies the resource pool where the vApp will be added This value is ignored if the <parent-virtual-app> element is specified.
Yes Conditional If <cluster-compute-resource> and <parent-virtual-app> are not specified, this element is required. Yes Yes
virtual-app spec
Specifies the vApp name that you want to update Valid value: String Specifies the updates needed to the vApp configuration For more information about the child elements of <spec>, see spec for vApp The name of the user If no user name is specified, the request is executed with the user specified in the configuration. The password corresponding to the specified user name
user-name
No
password
The following code sample shows a sample adapter request for the Update_VApp_Configuration operation. Sample adapter request for the Update_VApp_Configuration operation
<vmware-infrastructure-request> <soap-url/> <transport/> <user-name/> <password/> <operation-type>Configure_VApp</operation-type> <operation-name>Update_VApp_Configuration</operation-name> <parameters> <virtual-app>Bug</virtual-app> <spec> <eula>End user licence aggrement</eula> <ovf-environment-transport>iso</ovf-environment-transport> <install-boot-required>true</install-boot-required> <install-boot-stop-delay>15</install-boot-stop-delay> <annotation>This is an updated vapp configuration</annotation>
<ip-assignment> <ip-allocation-policy>transientPolicy</ip-allocation-policy> <ip-protocol>IPv6</ip-protocol> <supported-allocation-scheme>ovfenv</supported-allocation-scheme> <supported-ip-protocol>IPv6</supported-ip-protocol> </ip-assignment> <product> <info> <app-url>http://abc.xyz.com/</app-url> <class-id>ab_123</class-id> <full-version>1.0_builds_full_version</full-version> <name>TestProductUpdate</name> <product-url>http://google.co.in</product-url> <vendor>TestVendor</vendor> <version>1.0</version> <vendor-url>This is to add a product property.</vendor-url> </info> </product> <property-list> <property> <operation>add</operation> <info> <category>TestCategory0</category> <default-value>TestProperty0</default-value> <type>string</type> <id>Property_0</id> <description>Adding Test Property0</description> <key>0</key> <label>TestLabel0</label> </info> </property> <property> <operation>add</operation> <info> <category>TestCategory1</category> <default-value>TestProperty1</default-value> <type>string</type> <id>Property_1</id> <description>Adding Test Property1</description> <key>1</key> <label>TestLabel1</label> </info> </property> </property-list> <ovf-section-list> <ovf-section> <operation>add</operation> <info> <key>3</key> <contents>Test Contents3</contents> <namespace>Testing3</namespace> <type>TestOVFSection3</type> <at-envelope-level>true</at-envelope-level> </info> </ovf-section> <ovf-section>
<operation>add</operation> <info> <key>4</key> <contents>Test Contents4</contents> <namespace>Testing4</namespace> <type>TestOVFSection4</type> <at-envelope-level>true</at-envelope-level> </info> </ovf-section> </ovf-section-list> <entity-config-list> <entity-config> <key>TestVM</key> <start-action>none</start-action> <start-delay>10</start-delay> <start-order>0</start-order> <stop-action /> <stop-delay /> <tag>Test1</tag> </entity-config> <entity-config> <key>TestCloneVM</key> <start-action>none</start-action> <start-delay>12</start-delay> <start-order>1</start-order> <stop-action /> <stop-delay>20</stop-delay> <tag>Test2</tag> </entity-config> </entity-config-list>
The following code sample shows the response for the sample Update_VApp_Configuration operation. Sample adapter response for the Update_VApp_Configuration operation
<vmware-infrastructure-response> <metadata> <status>success</status> </metadata> <UpdateVAppConfigResponse></UpdateVAppConfigResponse> </vmware-infrastructure-response>
Monitor adapter events for VMware Infrastructure

The event monitor adapter monitors the VMware Infrastructure application for events to occur, including Vmotion events. The SNMP monitor adapter is responsible for receiving traps from VMware Infrastructure application and forwarding them in an XML format.
Event monitor adapter for VMware Infrastructure SNMP monitor adapter for VMware Infrastructure
Event monitor adapter for VMware Infrastructure

The events to be monitored by the event monitor adapter are specified in the event monitor adapter configuration. You can use Rules to specify the action to be taken when the response is received.
Supported event types for VMware Infrastructure

The monitor adapter supports all the event types and sub-types that are generically supported by VMware Infrastructure:
Event types and sub-types supported by the event monitor adapter Event type AlarmEvent AuthorizationEvent ClusterEvent CustomFieldEvent DatastoreEvent GeneralEvent HostEvent Description Indicates alarm events such as AlarmCreatedEvent Indicates authorization events such as PermissionEvent and RoleEvent Indicates cluster events such as ClusterCreatedEvent and ClusterDestroyedEvent Indicates custom field events such as CustomFieldValueChangedEvent Indicates datastore events such as DatastoreDestroyedEvent Indicates general events such as GeneralHostErrorEvent Indicates host related events such as HostAddedEvent
LicenseEvent ResourcePoolEvent ScheduledTaskEvent SessionEvent TaskEvent TemplateUpgradeEvent UpgradeEvent
Indicates licensing events such as HostLicenseExpiredEvent Indicates resource pool related events such as ResourcePoolCreatedEvent Indicates scheduled task events such as ScheduledTaskCreatedEvent Indicates session events such as UserLogoutSessionEvent Indicates task events Indicates template upgrade events such as TemplateUpgradedEvent Indicates events converted from VirtualCenter 1.x All upgraded events are converted to string values. UserUpgradeEvent is an example. Indicates virtual machine events such as VmDeployedEvent
VmEvent
VmBeingHotMigratedEvent Indicates that a virtual machine is being hot migrated
You can obtain the complete list of supported events from http://www.vmware.com/support/developer/vc-sdk/visdk2xpubs/ReferenceGuide/index.html
Event monitor adapter events for VMware Infrastructure

If the event monitor adapter is configured to receive VmPoweredOffEvent and VmPoweredOnEvent event types and the return-history element is set to true, an event similar to the one shown in the following code sample is the first event sent. Note This event contains a collection of events that are returned from the VMware Infrastructure client history.
Event monitor adapter
<vmware-monitor-event> <returnval> <version>1</version> <changeSet> <name>latestPage</name> <op>assign</op> <ArrayOfEvent> <VmPoweredOffEvent> <key>23889</key> <chainId>23886</chainId> <createdTime>2008-08-28T21:10:26.016999Z</createdTime> <userName>apilch</userName> <datacenter> <name>Dev</name> <Datacenter>datacenter-6</Datacenter> </datacenter> <computeResource> <name>xyz.bmc.com</name>
<ComputeResource>domain-s2278</ComputeResource> </computeResource> <host> <name>xyz.bmc.com</name> <HostSystem>host-32</HostSystem> </host> <vm> <name>DEV_VM_Solaris10</name> <VirtualMachine>vm-2799</VirtualMachine> <uuid> 4203262b-f529-4ded-dc96-fe9fdba4b38e</uuid> </vm> <fullFormattedMessage>DEV_VM_Solaris10 on xyz.bmc.com in Dev is powered off</fullFormattedMessage> <template>false</template> <virtualCenter>vCenter1.bmc.com</virtualCenter> </VmPoweredOffEvent> <VmPoweredOnEvent> <key>23883</key> <chainId>23881</chainId> <createdTime>2008-08-28T20:03:09.14Z</createdTime> <userName>apilch</userName> <datacenter> <name>Dev</name> <Datacenter>datacenter-6</Datacenter> </datacenter> <computeResource> <name>xyz.bmc.com</name> <ComputeResource>domain-s2278</ComputeResource> </computeResource> <host> <name>xyz.bmc.com</name> <HostSystem>host-32</HostSystem> </host> <vm> <name>DEV_VM_Solaris10</name> <VirtualMachine>vm-2799</VirtualMachine> <uuid> 4203262b-f529-4ded-dc96-fe9fdba4b38e</uuid> </vm> <fullFormattedMessage>DEV_VM_Solaris10 on xyz.bmc.com in Dev is powered on</fullFormattedMessage> <template>false</template> <virtualCenter>vCenter1.bmc.com</virtualCenter> </VmPoweredOnEvent> </ArrayOfEvent>
</changeSet> </returnval> </vmware-monitor-event>
If a single VmPoweredOnEvent event is captured by the event monitor adapter, an event similar to the following code sample is sent. XML sample of a single VmPoweredOnEvent event captured by the monitor adapter
<vmware-monitor-event> <returnval> <version>2</version> <changeSet> <name>latestPage[23850]</name> <op>remove</op> </changeSet> <changeSet> <name>latestPage[23937]</name> <op>add</op> <VmPoweredOnEvent> <key>23937</key> <chainId>23935</chainId> <createdTime>2008-09-01T08:47:23.453125Z</createdTime> <userName>Administrator</userName> <datacenter> <name>Dev</name> <Datacenter>datacenter-6</Datacenter> </datacenter> <computeResource> <name>BMC-3.bmc.com</name> <ComputeResource>domain-s2115</ComputeResource> </computeResource> <host> <name>BMC-3.bmc.com</name> <HostSystem>host-2118</HostSystem> </host> <vm> <name>Vm1</name> <VirtualMachine>vm-2681</VirtualMachine> <uuid> 4203262b-f529-4ded-dc96-fe9fdba4b38e</uuid> </vm> <fullFormattedMessage>Vm1 on BMC-3.bmc.com in Dev is powered on</fullFormattedMessage> <template>false</template> <virtualCenter>vCenter1.bmc.com</virtualCenter> </VmPoweredOnEvent> </changeSet> </returnval> </vmware-monitor-event>
If a single Vmotion event is captured by the event monitor adapter, an event similar to the one shown in the following code sample is sent.
XML sample of a single Vmotion event captured by the monitor adapter

<vmware-monitor-event> <returnval> <version>3</version> <changeSet> <name>latestPage[2652701]</name> <op>remove</op> </changeSet> <changeSet> <name>latestPage[2661945]</name> <op>add</op> <VmBeingHotMigratedEvent> <key>2661945</key> <chainId>2661944</chainId> <createdTime>2008-09-05T04:18:04.00493Z</createdTime> <userName>user1</userName> <datacenter> <name>Datacenter</name> <Datacenter>datacenter-2</Datacenter> </datacenter> <computeResource> <name>Cluster1</name> <ClusterComputeResource>domain-c113</ClusterComputeResource> </computeResource> <host> <name>houperfesx042.bmc.com</name> <HostSystem>host-150</HostSystem> </host> <vm> <name>houperfmsvm1232</name> <VirtualMachine>vm-131</VirtualMachine> <uuid> 4203262b-f529-4ded-dc96-fe9fdba4b38e</uuid> </vm> <fullFormattedMessage>Migrating vm1232 from esx042.abc.com to esx043.abc.com in Datacenter</fullFormattedMessage> <template>false</template> <destHost> <name>esx043.abc.com</name> <HostSystem>host-137</HostSystem> </destHost> <virtualCenter>vCenter2.bmc.com</virtualCenter> </VmBeingHotMigratedEvent> </changeSet> </returnval> </vmware-monitor-event>
SNMP monitor adapter for VMware Infrastructure

The monitor adapter supports v1 and v2c SNMP traps. This adapter does not support multiple configuration nodes, but you can configure multiple SNMP monitor adapters within the Grid Manager, with each monitor adapter having an unique configuration node and adapter name.
SNMP monitor adapter event for VMware Infrastructure

The monitor adapter receives SNMP traps published by the VMware application. To perform actions related to traps, you would design processes and implement rules. The following table shows the monitor adapter event elements with the MIB definition. Event node elements: monitor adapter with the MIB definition Element host Description The host that generated the trap
sysuptime Represents the time at which the trap was generated, expressed in 1/100 seconds since the start up of the application that generated the trap enterprise The enterprise OID or string This element will be used for v1 traps only, it will be empty for v2c traps. trap-type varbinds varbind oid name value The trap type string. Contains the <varbind> elements Contains the details of an incoming trap The OID for the incoming trap The OID reference name for the incoming trap The OID value for the incoming trap Note To use the data from the monitor adapter event in the process triggered by a rule, you create a Job Input Parameter named 'inputevent' on the Start Activity of that process. The monitor adapter event will automatically populate this Input.
The following code sample illustrates a sample format for the trap sent by VMware Infrastructure. XMl Sample for monitor adapter with MIB Definition
<trap> <host>127.21.10.22</host> <sysuptime>21088065</sysuptime> <enterprise>vmwTraps</enterprise> <trap-type>vpxdTrap</trap-type> <varbinds> <varbind> <oid>.1.3.6.1.4.1.6876.50.301</oid> <name>vpxdTrapType</name> <value>vm</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.302</oid> <name>vpxdHostName</name> <value></value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.303</oid> <name>vpxdVMName</name> <value>win1</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.304</oid> <name>vpxdNewStatus</name> <value>Green</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.305</oid> <name>vpxdOldStatus</name> <value>Red</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.306</oid> <name>vpxdObjValue</name> <value>VM is powered on - (State = Powered Off)</value> </varbind> </varbinds> </trap>
The following table shows the monitor adapter event elements without MIB definition. Event node elements: monitor adapter without MIB definition Element host sysuptime enterprise Description The host that generated the trap Represents the time at which the trap was generated, expressed in 1/100 seconds since the start up of the application that generated the trap The enterprise OID or string This element will be used for v1 traps only, it will be empty for v2c traps.
generic-trap-type The generic trap type
specific-trap-type The specific trap type varbinds varbind oid value Contains the <varbind> element Contains the details of an incoming trap The OID for the incoming trap The OID value for the incoming trap Note To use the data from the monitor adapter event in the process triggered by a rule, a Job Input Parameter, 'inputevent', should be created on the Start Activity of that process. The monitor adapter event will automatically populate this Input.
The following code sample illustrates a sample format for the trap sent by VMware Infrastructure, without the MIBS directory defined in the adapter configuration. XML sample for the monitor adapter without MIB Definition
<trap> <host>127.21.10.22</host> <sysuptime>135045203</sysuptime> <enterprise>.1.3.6.1.4.1.6876.50</enterprise> <generic-trap-type>6</generic-trap-type> <specific-trap-type>201</specific-trap-type> <varbinds> <varbind> <oid>.1.3.6.1.4.1.6876.50.301</oid> <value>vm</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.302</oid> <value></value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.303</oid> <value>win2</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.304</oid> <value>Yellow</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.305</oid> <value>Red</value> </varbind> <varbind> <oid>.1.3.6.1.4.1.6876.50.306</oid> <value>New Alarm - (State = Powered Off)</value> </varbind> </varbinds> </trap>
Adapter request elements for VMware Infrastructure adapter

This appendix provides the definitions of the child elements of adapter request elements and information about the short guest operating identifiers.
Guest operating system identifiers for VMware Infrastructure

The following table specifies the identifiers for guest operating systems: guest-id darwinGuest dosGuest freebsd64Guest freebsdGuest mandrake64Guest mandrakeGuest netware4Guest netware5Guest netware6Guest nld9Guest oesGuest os2Guest other24xLinux64Guest other24xLinuxGuest other26xLinux64Guest other26xLinuxGuest otherGuest otherGuest64 otherLinux64Guest otherLinuxGuest redhatGuest rhel2Guest rhel3_64Guest rhel3Guest rhel4_64Guest rhel4Guest sjdsGuest Description darwin MS-DOS FreeBSD x64 FreeBSD Mandrake Linux (64-bit) (experimental) Mandrake Linux Novell NetWare 4 Novell NetWare 5.1 Novell NetWare 6.x Novell Linux Desktop 9 Open Enterprise Server OS/2 Linux 2.4x Kernel (64-bit) (experimental) Linux 2.4x Kernel Linux 2.6x Kernel (64-bit) (experimental) Linux 2.6x Kernel Other Operating System Other Operating System (64-bit) (experimental) Linux (64 bit) (experimental) Other Linux Red Hat Linux 2.1 Red Hat Enterprise Linux 2 Red Hat Enterprise Linux 3 (64-bit) (experimental) Red Hat Enterprise Linux 3 Red Hat Enterprise Linux 4 (64 bit) (experimental) Red Hat Enterprise Linux 4 Oracle Java Desktop System
sles64Guest slesGuest solaris10_64Guest solaris10Guest solaris6Guest solaris7Guest solaris8Guest solaris9Guest suse64Guest suseGuest turboLinuxGuest ubuntu64Guest ubuntuGuest win2000AdvServGuest win2000ProGuest win2000ServGuest win31Guest win95Guest win98Guest winMeGuest winNetBusinessGuest
SUSE Linux Enterprise Server 9 (64 bit) (experimental) SUSE Linux Enterprise Server 9 Oracle Solaris10 (64 bit) (experimental) Oracle Solaris 10 (32 bit) (experimental) Oracle Solaris 6 Oracle Solaris 7 Oracle Solaris 8 Oracle Solaris 8 SUSE Linux (64-bit) (experimental) SUSE Linux Turbolinux Ubuntu Linux (64-bit) (experimental) Ubuntu Linux Microsoft Windows 2000 Advanced Server Microsoft Windows 2000 Professional Microsoft Windows 2000 Server Microsoft Windows 3.1 Microsoft Windows 95 Microsoft Windows 98 Microsoft Windows Millenium Edition Microsoft Windows Small Business Server 2003
winNetEnterprise64Guest Microsoft Windows Server 2003, Enterprise Edition (64-bit) (experimental) winNetEnterpriseGuest winNetStandard64Guest winNetStandardGuest winNetWebGuest winNTGuest winVista64Guest winVistaGuest winXPHomeGuest winXPPro64Guest winXPProGuest Microsoft Windows Server 2003, Enterprise Edition Microsoft Windows Server 2003, Standard Edition (64 bit) (experimental) Microsoft Windows Server 2003, Standard Edition Microsoft Windows Server 2003, Web Edition Microsoft Windows NT 4 Windows Vista (64 bit) (experimental) Microsoft Windows Vista Microsoft Windows XP Home Edition Microsoft Windows XP Professional Edition (64 bit) (experimental) Microsoft Windows XP Professional
spec for vApp

Specifies how to update a vApp configuration.
The following table contains the definition for the child elements of spec. Child elements - spec Element product Definition Specifies information about the product installed in the virtual machines in the vApp For information about the child elements of <product>, see product Specifies the list of properties for the vApp Even a single property must be contained in the <property-list> element. For infomation about the child elements of <property-list>, see property-list Specifies the IP assignment policy For information about the child elements of <ip-assignment>, see ip-assignment Specifies the end-user license agreements Valid value: String Specifies the non-interpreted OVF metadata sections Even a single <ovf-section> element must be contained in the <ovf-section-list> element. For information about the child elements of <ovf-section-list>, see ovf-section Required No
property-list
No
ip-assignment
No
eula ovf-section-list
No No
ovf-environment transport
Specifies the list of transports to use for the properties of the vApp No Valid values: iso, com.vmware.guestInfo
install-boot-stop-delay Specifies the delay, in seconds, to wait for the virtual machine to power off after the initial boot For example, a value of 0 indicates wait forever. Valid value: Number install-boot-required Specify this element on a virtual machine object, if the virtual machine needs an initial boot before the deployment is complete For a VApp object, this element indicates that one or more virtual machines need an initial reboot This flag is automatically reset once the reboot process is complete. Valid value: Boolean Specifies the configuration of sub-entities such as virtual machine or vApp container The entity list contains the updated configuration for one or more than one sub-entities. Even for a single sub-entity, you must provide the configuration inside the <entity-config-list> element. For more information about the child elements, see entity-config Specifies the updated description of the vApp Valid value: String
Conditional Used only if <install-boot-required> is set to true No
entity-config-list
No
annotation
No
The following figure shows the sample for spec. XML sample for spec
<spec> <product> <info> <app-url></app-url> <class-id></class-id> <full-version></full-version> <name></name> <product-url></product-url> <vendor></vendor> <version></version> <vendor-url></vendor-url> </info> </product> <ovf-environment-transport></ovf-environment-transport> <install-boot-required></install-boot-required> <install-boot-stop-delay></install-boot-stop-delay> <annotation></annotation> <property-list> <property> <operation></operation> <info> <category></category> <default-value></default-value> <type></type> <id></id> <description>/description> <key></key> <label></label> </info> </property> </property-list> <ip-assignment> <ip-allocation-policy></ip-allocation-policy> <ip-protocol></ip-protocol> </ip-assignment> <eula></eula> <ovf-section-list> <ovf-section> <operation></operation> <info> <key></key> <contents></contents> <namespace></namespace> <type></type> <at-envelope-level></at-envelope-level> </info> </ovf-section> <ovf-environment-transport></ovf-environment-transport> <install-boot-required></install-boot-required> <install-boot-stop-delay></install-boot-stop-delay> <entity-config> <destroy-with-parent></destroy-with-parent> <key></key>
<start-action></start-action> <start-delay></start-delay> <start-order></start-order> <stop-action></stop-action> <stop-delay></stop-delay> <tag></tag> <waiting-for-guest>e</waiting-for-guest> </entity-config> <annotation></annotation> </spec> </ovf-section> </ovf-section-list> <entity-config-list> <entity-config> <destroy-with-parent></destroy-with-parent> <key></key> <start-action></start-action> <start-delay></start-delay> <start-order></start-order> <stop-action></stop-action> <stop-delay></stop-delay> <tag></tag> </entity-config> <entity-config> <destroy-with-parent></destroy-with-parent> <key></key> <start-action></start-action> <start-delay></start-delay> <start-order></start-order> <stop-action></stop-action> <stop-delay></stop-delay> <tag></tag>
</entity-config> </entity-config-list> </spec>
property-list
Specifies the list of vApp property descriptions, including deployment values. The following table contains the definition for the child elements of property-list. Child elements -property-list Element operation Definition Specifies the type of operation being performed on the specified virtual device Valid value: add, edit Specifies a user-visible description for the category to which the property belongs Valid value: String Required Yes
category
No
default-value Specifies the default value of a field Valid value: String description id Specifies the description for the field Valid value: String Specifies the ID of the property Valid value: String without whitespace craracters
No No Conditional This element cannot be empty for a property. This element must be specified at creation and cannot be set to empty string. No No
label type
Specifies the display name of the property Valid value: String Specifies the type of the property Valid values: "string", "int", "boolean", "real", "ip" and " ip:network" Specifies an unique integer key for the property Specifies the value of the field at the time of deployment Valid value for String type of property: string Valid value for Integer type of property: Any positive integer from 0 to 5000 Valid value for Boolean type of property: True, False Valid value for Real type of property: '- infinity' to '+ infinity' Valid value for IP type of property: Any IPv4 address in dot-decimal notation or an IPv6 address in colon-hexadecimal notation Valid value of IP:network type of property: An IP address in dot-notation (IPv4) and colon-hexadecimal (IPv6) on a particular network. The behavior of this type depends on the <ip-allocation-policy> element.
key value
Yes No
The following figure shows the sample for property-list. XML sample for property-list
<property-list> <property> <operation></operation> <info> <category></category> <default-value></default-value> <type></type> <id></id> <description></description> <key></key> <label></label> </info> </property> </property-list>
product
Contains information about the products installed on the virtual machines in the vApp container. The following table contains the definition for the child elements of product. Child elements -product Element app-URL Definition Required
Specifies the URL for the entry point to the application No Valid value: String
full-version Specifies the full-version of the product Valid value: String key name Specifies an unique key for the product Valid value: Integer Specifies the name of the product Valid value: String
No Yes No No No No No
product-url Specifies the URL to the product home page Valid value: String vendor vendor-url version Specifies the vendor of the product Valid value: String Specifies the URL to the vendor home page Valid value: String Specifies the short version of the product Valid value: String
The following figure shows the sample for product.
XML sample for product

<product> <info> <app-url></app-url> <class-id></class-id> <full-version></full-version> <name></name> <product-url>/product-url> <vendor></vendor> <version></version> <vendor-url></vendor-url> </info> </product>
ovf-section
Specifies the list of uninterpreted OVF metadata sections. The ovf-section encapsulates uninterpreted metadata sections in an OVF descriptor. When an OVF package is imported, the non-interpreted sections are stored as ovf-section object. During the creation of an OVF package, these sections are placed in the OVF descriptor. The following table contains the definition for the child elements of ovf-section. Child elements - ovf-section Element operation Definition Required
Specifies the type of operation being performed on the specified virtual machine Yes No No
at-envelope-level Specifies whether it is a global envelope section contents Specifies the XML fragment including the top-level <section> element The fragment is self-contained with all the required namespace definitions. Valid value: String Specifies the unique key used to identify the section Valid value: Number Specifies the namespace for the value in xsi:type attribute Valid value: String Specify the value of the xsi:type attribute, not including the namespace prefix Valid value: String
key namespace type
Yes No No
The following figure shows the sample for ovf-section. XML sample for ovf-section
<ovf-section> <operation></operation> <info> <key></key> <contents></contents> <namespace></namespace> <type></type> <at-envelope-level></at-envelope-level> </info> <ovf-section>
ip-assignment
Specifies details about Internet Protocol (IP) address assignments The following table contains the definition for the child elements of ip-assignment. Child elements - ip-assignment Element ip-allocation-policy Definition Specifies how the IP allocation should be managed by the VMware Infrastructure platform This value is typically specified by the deployer. Valid values: transientPolicy, fixedPolicy, and dhcpPolicy Specifies the chosen IP protocol for the deployment Valid values: String values such as IPv4 and IPv6 Required No
ip-protocol
No No No
supported-allocation-scheme Specifies the IP allocation schemes supported by the guest software Valid values: ovfenv, dhcp supported-ip-protocol Specify the IP protocols supported by the guest software Valid values: IPv4, IPv6
The following figure shows the sample for ip-assignment. XML sample for ip-assignment
<ip-assignment> <ip-allocation-policy></ip-allocation-policy> <ip-protocol></ip-protocol> <supported-allocation-scheme></supported-allocation-scheme> <supported-ip-protocol></supported-ip-protocol> </ip-assignment>
address-list
Lists the IP addresses of the DNS servers The following table contains the definition for the child elements of address-list.
Child elements - address-list Element Definition address The IP addresses of the DNS servers, placed in order of preference When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set. Required No
The following figure shows the sample for address-list. XML Sample for address-list
<address-list> <address></address> <address></address> ... <address-list>
console-ip-route-config
Specifies the IP route configuration of the service console. The following table contains the definition for the child elements of console-ip-route-config. Child elements - console-ip-route-config Element Definition Required
default-gateway Specifies the default gateway address No gateway-device Specifies the gateway device No
The following figure shows the sample for console-ip-route-config. XML Sample for console-ip-route-config
<console-ip-route-config> <default-gateway>127.21.10.154</default-gateway> <gateway-device></gateway-device> </console-ip-route-config>
device-change-list for removing devices

Set of virtual devices being removed by the operation. The remove operation is supported.
Removing a hard disk

This operation allows you to remove a hard disk from a virtual machine.
The following figure shows the sample for device-change-list for removing a hard disk. The permissible values of the elements are: disk-name - The name of the hard disk to be removed. XML Sample of device-change-list for removing a hard disk
<device-change-list> <device-change> <operation>remove</operation> <file-operation>destroy</file-operation> <device type="VirtualDisk"> <disk-name></disk-name> </device> </device-change> </device-change-list>
Removing a CD ROM drive

This operation enables you to remove a CD ROM device from a virtual machine. The following figure shows the sample for device-change-list for removing a CD ROM drive. The permissible values of the element is: cdrom - The name of the CD ROM to be removed. XML Sample of device-change-list for removing a CD ROM drive
<device-change-list> <device-change> <operation>remove</operation> <device> <cdrom></cdrom> </device> </device-change> </device-change-list>
Removing an ethernet adapter

This operation allows you to remove an ethernet adapter from a virtual machine. The following figure shows the sample for device-change-list for removing an ethernet adapter. The permissible values of the element is: ethernet-adapter - The name of the ethernet adapter to be removed. XML Sample of device-change-list for removing an ethernet adapter
<device-change-list> <device-change> <operation>remove</operation> <device> <ethernet-adapter></ethernet-adapter> </device> </device-change> </device-change-list>
device-change-list for updating devices

Set of virtual devices being updated by the operation. The Edit operation is supported.
Updating a SCSI controller configuration

This operation allows you to update the configuration of a SCSI controller associated with a virtual machine. The following figure shows the sample for device-change-list for updating a SCSI Controller. For updating a SCSI controller, the permissible values of the elements are: scsi-controller -The name of the SCSI Controller to be updated. shared-bus - Mode for sharing the SCSI bus. Valid values are physicalSharing, virtualSharing, and noSharing. XML Sample of device-change-list for updating a SCSI Controller
<device-change-list> <device-change> <operation>edit</operation> <device type="VirtualLsiLogicController"> <scsi-controller>SCSI Controller 0</scsi-controller> <bus-number>0</bus-number> <shared-bus>physicalSharing</shared-bus> </device> </device-change> </device-change-list>
Updating an ethernet adapter configuration

This operation enables you to update the configuration of an ethernet adapter associated with a virtual machine. The following figure shows the sample for device-change-list for updating an ethernet adapter configuration. For updating an ethernet adapter, the permissible values of the elements are: device-type - Valid value is VirtualPCNet32. ethernet-adapter - Mode for sharing the SCSI bus. Valid values are physicalSharing, virtualSharing, and noSharing. start-connected - The flag specifying whether to connect the device when the virtual machine starts. allow-guest-control - The flag that allows the guest to control the device when the device is connected. connected - The flag that indicates whether the device is currently connected. This element is valid only when the virtual machine is running. address-type - Specifies the MAC address type. Valid values are manual and assigned. Manual indicates a statically assigned MAC address and assigned indicates that the MAC address is assigned by the Virtual
Center. mac-address - The MAC address assigned to the virtual network adapter. Clients can set this property to any of the permissible address types. The server may override the specified value for Assigned, if the value does not fall within the acceptable ranges or if the value is determined to be a duplicate. wake-on-lan-enabled - Indicates whether the wake-on-LAN feature is enabled on the virtual network adapter. Clients can set this property to selectively enable or disable the wake-on-LAN feature. XML Sample of device-change-list for updating an ethernet adapter configuration
<device-change-list> <device-change> <operation>edit</operation> <device type="VirtualPCNet32"> <ethernet-adapter>NetAdapter1</ethernet-adapter> <backing type="VirtualEthernetCardNetworkBackingInfo"> <device-name>DummyNetwork</device-name> </backing> <connectable> <start-connected>true</start-connected> <allow-guest-control>true</allow-guest-control> <connected>true</connected> </connectable> <controller-key>0</controller-key> <unit-number>0</unit-number> <address-type>assigned</address-type> <mac-address></mac-address> <wake-on-lan-enabled>false</wake-on-lan-enabled> </device-change> </device-change-list>
ip-route-config
Specifies the IP route configuration of the host. The following table contains the definition for the child elements of ip-route-config. Child elements -ip-route-config Element Definition Required
default-gateway Specifies the default gateway address No
The following figure shows the sample for ip-route-config. XML Sample for ip-route-config
<ip-route-config> <default-gateway>127.21.10.154</default-gateway> </ip-route-config>
cpu-feature-mask-list
An XML document that specifies the CPU feature compatibility masks. The following table contains the definition for the child elements of cpu-feature-mask-list. Child elements -cpu-feature-mask-list Element Definition Required
operation The type of operation being performed on the specified virtual device No Valid values: add level vendor eax ebx ecx edx Level (EAX input to CPUID) Used if this mask is for a particular vendor A string representing the required EAX bits A string representing the required EBX bits A string representing the required ECX bits A string representing the required EDX bits No No No No No No
The following figure shows the sample for cpu-feature-mask-list. XML Sample for cpu-feature-mask-list
<cpu-feature-mask-list> <cpu-feature-mask> <operation>add</operation> <info> <level></level> <vendor></vendor> <eax></eax> <ebx></ebx> <ecx></ecx> <edx></edx> </info> </cpu-feature-mask> ............ </cpu-feature-mask-list>
cpu-allocation
Specifies the resource limits for a CPU. The following table contains the definition for the child elements of cpu-allocation. Child elements - cpu-allocation Element Definition Required
expandable-reservation In a resource pool with an expandable reservation, the reservation on a resource pool can grow beyond the specified value, if the parent resource pool has unreserved resources. A non-expandable reservation is called a fixed reservation. This property is ignored for virtual machines. Valid values: true , false reservation Amount of resource that is guaranteed available to the virtual machine or resource pool Reserved resources are not wasted if they are not used. If the utilization is less than the reservation, the resources can be used by other running virtual machines. The amount of CPU to be reserved should be less than the CPU limit specified for the virtual machine. Valid value: Number The utilization of a virtual machine or a resource pool must not exceed this limit, even if there are available resources This is typically used to ensure a consistent performance of virtual machines or resource pools independent of available resources. If limit is set to -1, there is no fixed limit on resource usage and is only bounded by available resources and shares. The unit of measurement is MHz. The number of shares allocated The value is used to determine resource allocation in the case of resource contention. There is no unit for this value. It is a relative measure based on the settings for other resource pools. This value is only set if the level is set to custom. Only shares with custom values can be compared. If this level is not set to custom, this value is ignored. The allocation level The level is a simplified view of shares. Levels map to a pre-determined set of numeric values for shares. Valid values: custom - Shares are specified in the shares column. high - Shares = 2000 * number of virtual CPUs. low - Shares = 500 * number of virtual CPUs. normal - Shares = 1000 * number of virtual CPUs. If the shares value does not map to a predefined size, the level is set as custom.
Conditional Mandatory for the Create_VApp operation Conditional Mandatory for the Create_VApp operation
limit
Conditional Mandatory for the Create_VApp operation
shares
Conditional Required if level is set to custom
level
Conditional Mandatory for the Create_VApp operation
The following figure shows the sample for cpu-allocation. XML Sample for cpu-allocation
<cpu-allocation> <expandable-reservation></expandable-reservation> <reservation></reservation> <limit></limit> <shares> <shares></shares> <level></level> </shares> </cpu-allocation>
console-vnic-list
Lists the virtual network adapters configured for use by the Service Console. The following table contains the definition for the child elements of console-vnic-list. Child elements - console-vnic-list Element Definition Required No No No No
change-operation The change operation to apply on this configuration specification Valid values: add, edit, remove device portgroup dhcp The VirtualNic device to which the configuration applies The name of port group to which the virtual NIC connects The flag to indicate whether DHCP is enabled Valid values: true, false Note: If this property is set to true, you cannot set the ipAddress and the subnetMask strings explicitly. The IP address currently used by the network adapter All IP addresses are specified using IPv4 dot notation. For example, "192.168.0.1". Subnet addresses and netmasks are specified using the same notation. Note: When DHCP is enabled, this property reflects the current IP configuration and cannot be set. When DHCP is not enabled, this property can be set explicitly. The subnet mask When DHCP is not enabled, this property can be set explicitly. When DHCP is enabled, this property reflects the current IP configuration and cannot be set. The media access control (MAC) address of the virtual network adapter
ip-address
No
subnet-mask
Conditional
mac
No
The following figure shows the sample for console-vnic-list. XML Sample for console-vnic-list
<console-vnic-list> <console-vnic> <change-operation></change-operation> <device></device> <portgroup></portgroup> <spec> <ip> <dhcp></dhcp> <ip-address></ip-address> <subnet-mask></subnet-mask> </ip> <mac></mac> </spec> </console-vnic> ............... </console-vnic-list>
device-change-list for adding devices

Set of virtual devices being added by the operation. The Add operation is supported. Note You must add a controller when you are adding a virtual disk (SCSI) and ethernet adapter (PCI controller). You can add multiple disks or adapters with one controller of the relevant type.
Adding a SCSI controller

This operation allows you to add a SCSI controller to a virtual machine. The following code sample shows the <device-change-list> for adding a SCSI controller. The permissible values of the elements are: <controllerType> VirtualBusLogicController VirtualLsiLogicController VirtualLsiLogicSASController ParaVirtualSCSIController <bus-number> The bus number associated with this controller, which, for this operation, must be 0 <shared-bus> The mode for sharing the SCSI bus: hysicalSharing virtualSharing noSharing
XML Sample of <device-change-list> for adding a SCSI controller
<device-change-list> <device-change> <operation>add</operation> <device type="ControllerType"> <bus-number>0</bus-number> <device>0</device> <shared-bus></shared-bus> </device> </device-change> <device-change-list>
Adding a virtual disk

This operation allows you to add a virtual disk. The following figure shows the sample for device-change-list for adding a virtual disk. For adding a virtual disk, the permissible values of the elements are: file-name -The filename for the host using for the backing operation. disk-mode -The disk access mode. Valid values are persistent, independent_persistent, independent_nonpersistent, and nonpersistent. device-type -valid value is VirtualDisk. split - The flag that indicates whether the virtual disk file is split or monolithic. Valid values are true and false. If the value is set to true, the virtual disk is stored in multiple files, with the size of each file set to 2 GB. write-through - The flag that indicates whether the disk writes goes directly to the file system or must be buffered. Valid values are true and false. thin-provisioned - The flag that indicates whether the virtual disk backing file should be allocated lazily (by using thin provisioning). This flag is used only by the underlying filesystems that support the configuration of the provisioning policy on a file basis. VMFS3 is such a file system. Valid values are true and false. controller-key - The property that contains the key property value of the controller device. Valid value is 0. unit-number - The unit number of the specified device on its controller. Valid value is 1. capacity-inKB - Capacity of this virtual disk, in kilobytes (KB). backing type -valid value is VirtualDiskFlatVer2BackingInfo. XML Sample of device-change-list for adding a virtual disk
<device-change-list> <device-change> <operation>add</operation> <file-operation>create</file-operation> <device type="VirtualDisk"> <backing type="VirtualDiskFlatVer2BackingInfo"> <file-name></file-name> <disk-mode></disk-mode> <split></split> <write-through></write-through> <thin-provisioned></thin-provisioned> </backing> <controller-key>0</controller-key> <unit-number>-1</unit-number> <capacity-inKB></capacity-inKB> </device> </device-change> </device-change-list>
Adding a PCI Controller

This operation allows you to add a PCI controller to a virtual machine. The following figure shows the sample for device-change-list for adding a PCI Controller. For adding a virtual disk, the permissible values of the elements are: controllerType - Valid value is VirtualPCIController. bus-number - Valid value is 0. XML Sample of device-change-list for adding a PCI Controller
<device-change-list> <device-change> <operation>add</operation> <device type="VirtualPCIController"> <bus-number>0</bus-number> <device>0</device> </device> </device-change> </device-change-list>
Adding an ethernet adapter

This operation allows you to add an ethernet adapter to a virtual machine. The following figure shows the sample for device-change-list for adding an ethernet adapter. For adding an ethernet adapter, the permissible values of the elements are: device-name - The name of the device on the host system. device type - valid value is VirtualPCNet32. backing type- valid value is VirtualEthernetCardNetworkBackingInfo. start-connected - The flag specifying whether to connect the device when the virtual machine starts. allow-guest-control - The flag that allows the guest to control the device when the device is connected.
connected - The flag that indicates whether the device is currently connected. This element is valid only when the virtual machine is running. address-type - Specifies the MAC address type. Valid values are manual and assigned. Manual indicates a statically assigned MAC address and assigned indicates that the MAC address is assigned by the Virtual Center. mac-address - The MAC address assigned to the virtual network adapter. Clients can set this property to any of the permissible address types. The server may override the specified value for Assigned, if the value does not fall within the acceptable ranges or if the value is determined to be a duplicate. wake-on-lan-enabled - Indicates whether the wake-on-LAN feature is enabled on the virtual network adapter. Clients can set this property to selectively enable or disable the wake-on-LAN feature. XML Sample of device-change-list for adding an ethernet adapter
<device-change-list> <device-change> <operation>add</operation> <device type="VirtualPCNet32"> <backing type="VirtualEthernetCardNetworkBackingInfo"> <device-name></device-name> </backing> <connectable> <start-connected></start-connected> <allow-guest-control></allow-guest-control> <connected></connected> </connectable> <controller-key>0</controller-key> <unit-number>0</unit-number> <address-type></address-type> <mac-address></mac-address> <wake-on-lan-enabled></wake-on-lan-enabled> </device> </device-change> </device-change-list>
Adding a CD ROM drive

This operation allows you to add a CD ROM device to a virtual machine. The following figure shows the sample for device-change-list adding a CD ROM drive. The permissible values of the elements are: device-name - The name of the device on the remote virtual machine. exclusive - The flag to indicate whether the virtual machine has exclusive access to the CD ROM device. backingInfoType - The valid values for backing type are VirtualCdromRemotePassthroughBackingInfo, and VirtualCdromRemoteAtapiBackingInfo. XML Sample of device-change-list for adding a CD ROM drive
<device-change-list> <device-change> <operation>add</operation> <device type="VirtualCdrom"> <key>0</key> <backing type="BackingInfoType"> <device-name></device-name> <exclusive>false</exclusive> </backing> </device> </device-change> <device-change-list>
location
The location of resources that the newly cloned virtual machine uses. The following table contains the definition for the child elements of location. Child elements -location Element resource-pool Definition The resource pool to which the virtual machine should be attached If the argument is not supplied, the current resource pool of the virtual machine is used. Required Conditional If cluster-compute-resource is not specified Conditional If resource-pool is not specified Conditional If the virtual machine has to be added to the default resource pool of the host and the host is a stand-alone host
cluster-compute-resource The cluster compute resource used to make the method call host-system DNS name of the target host for the virtual machine If resource pool is not specified, the current host is used. If resource pool is specified, and the target pool represents a stand-alone host, the host is used If resource pool is specified, and the target pool represents a DRS-enabled cluster, a host selected by DRS is used. If resource pool is specified and the target pool represents a cluster without DRS enabled, an InvalidArgument exception is thrown. Valid value: DNS name
datastore
The data store where the virtual machine should be located
No
transform
The transformation to perform on the disks The backend is free to ignore this hint if it is not valid for the current operation. This can be used by clients, for example, to create sparse disks for templates. Valid values: flat, sparse An optional list that allows specifying the datastore location for each virtual disk Sample format:
<disk\-list> <disk> <datastore></datastore> <disk\-name></disk\-name> </disk> <disk> <datastore></datastore> <disk\-name></disk\-name> </disk> ...... </disk\-list>
No
disk-list
No
Note: The specified disk must exist on the original virtual machine.
The following figure shows the sample for location. XML Sample for location
<location> <resource-pool>Resources</resource-pool> <cluster-compute-resource>TestCluster</cluster-compute-resource> <host-system>xyz.bmc.com</host-system> <datastore>storage1</datastore> <transform>flat</transform> <disk-list> <disk> <disk-name>Hard Disk 1</disk-name> <datastore>storage1</datastore> </disk> </disk-list> </location>
spec
Specifies the parameters needed to add a single host. The following table contains the definition for the child elements of spec. Child elements -spec
Element host-name port
Definition The DNS name of the host Valid values: dns name The port number for the connection If this is not specified, the default port number (port 902) is used. If this is a reconnect, the port number is unchanged. The administration account on the host The password for the administration account If this flag is set to true, the connection succeeds even if the host is already being managed by another Virtual Center server The original Virtual Center server loses connection to the host. Valid values: true, false The username to be used for accessing the virtual machine files on the disk
Required No No
user-name password force
No No Yes
vim-account-name
No No No
vim-account-password The password to be used with the <vimAccountName> property for accessing the virtual machine files on the disk folder Contains the inventory path of the folder in which to store the existing virtual machines on the host Default value: Discovered VM If you do not specify a value, VMware Virtual Center creates a folder.
The following figure shows the sample for spec. XML Sample for spec
<spec> <force></force> <host-name></host-name> <password></password> <port></port> <user-name></user-name> <vim-account-name></vim-account-name> <vim-account-password></vim-account-password> <folder></folder> </spec>
vnic-list
List of virtual network adapters to be added on the host, by the host operating system network adapter. The following table contains the definition for the child elements of vnic-list. Child elements -vnic-list Element portgroup Definition The name of port group to which virtual NIC connects Required No
dhcp
The flag to indicate whether DHCP is enabled Valid values: true, false If this property is set to true, the ipAddress and the subnetMask strings cannot be set explicitly. The IP address currently used by the network adapter All IP addresses are specified using IPv4 dot notation. Example: "192.168.0.1". Subnet addresses and netmasks are specified using the same notation. Note: When DHCP is enabled, this property reflects the current IP configuration and cannot be set. When DHCP is not enabled, this property can be set explicitly.
No
ip-address
No
subnet-mask The subnet mask When DHCP is not enabled, this property can be set explicitly. When DHCP is enabled, this property reflects the current IP configuration and cannot be set. mac The media access control (MAC) address of the virtual network adapter
Conditional
No
The following figure shows the sample for vnic-list. XML Sample for vnic-list
<vnic-list> <vnic> <portgroup></portgroup> <spec> <ip> <dhcp></dhcp> <ip-address></ip-address> <subnet-mask></subnet-mask> </ip> <mac></mac> </spec> </vnic> ... </vnic-list>
network-shaper
Specifies the network traffic shaping characteristics. Traffic shaping is used to configure the network utilization characteristics of a virtual machine. The following table contains the definition for the child elements of network-shaper. Child elements -network-shaper Element enabled peak-bps Definition specifies if the network shaper is enabled Valid values: true, false Required No
specifies the peak bandwidth, in bits per second No Valid value: number
average-bps Average bandwidth, in bits per second Valid value: number burst-size Burst size, in bytes Valid value: number
No No
The following figue shows the sample for network-shaper. XML Sample for network-shaper
<network-shaper> <enabled></enabled> <peak-bps></peak-bps> <average-bps></average-bps> <burst-size></burst-size> </network-shaper>
vswitch-list
Lists the Virtual switches configured on the host. Note For the security sub-tags, you must either specify values for all the parameters or provide values for none of them.
The following table contains the definition for the child elements of vswitch-list. Child elements - vswitch-list Element change-operation Definition This property indicates the change operation to apply on this configuration specification Valid values: add, edit, remove The name of the virtual switch The maximum length is 32 characters Valid value: String The number of ports that this virtual switch is configured to use Changing this setting does not take effect until the next reboot. The maximum value is 1024, although other constraints, such as memory limits, can establish a lower effective limit. The flag to indicate whether all traffic is seen on the port Valid values: true, false Required No
name
No
num-ports
No
allow-promiscuous
Conditional If mac-changes and forged-transmits are specified
mac-changes
The flag to indicate whether the Media Access Control (MAC) address can change Valid values: true, false The flag to indicate whether the virtual network adapter should be allowed to send network traffic with a different MAC address than that of the virtual network adapter Valid values: true, false Network adapter teaming policy includes failover and load balancing Valid values: loadbalance_ip - route based on ip hash. loadbalance_srcmac - route based on source MAC hash. loadbalance_srcid - route based on the source of the port ID. failover_explicit - use explicity failover order.
Conditional If allow-promiscuous and forged-transmits are specified Conditional If mac-changes and allow-promiscuous are specified. Conditional The NIC teaming policy elements are required only if the type of the network adapter bridge is BondBridge.
forged-transmits
policy
reverse-policy
The flag to indicate whether the teaming policy is applied to No inbound frames as well Example: If the policy is explicit failover, a broadcast request goes through uplink1 and comes back through uplink2. If the reverse policy is set, the frame is dropped when it is received from uplink2. This reverse policy is useful to prevent the virtual machine from getting reflections. Valid values: true, false Flag to specify whether to notify the physical switch if a link fails Valid values: true, false If this property is true, ESX Server will respond to the failure by sending a RARP packet from a different physical adapter, causing the switch to update its cache. No
notify-switches
rolling-order
The flag to indicate whether to use a rolling policy when restoring No links Example: Assume the explicit link order is (vmnic9, vmnic0), therefore vmnic9 goes down, vmnic0 comes up. However, when vmnic9 comes backup, if rollingOrder is set to be true, vmnic0 continues to be used, otherwise, vmnic9 is restored as specified in the explicitly order. Valid values: true, false The configured speed type to use while detecting link failure Valid values: exact: Use exact speed to detect link failure. minimum: Use minimum speed to detect failure empty string: Do not use link speed to detect failure No
check-speed
speed
A numeric value specifying the speed used to detect link failures
No
check-duplex
The flag to indicate whether to use the link duplex reported by the driver as link selection criteria If check-duplex is true, then fullDuplex is the configured duplex mode. The link is considered bad if the link duplex reported by driver is not the same as fullDuplex. If check-duplex is false, then fullDuplex is unused, and link duplexity is not used as a detection method. Specifies using the link in duplex mode Valid values: true, false
Yes
full-duplex
No No
check-error-percent The flag to indicate whether to use link error percentage to detect failure Valid values: true, false If check-error-percent is true, then percentage is the configured error percentage that is tolerated. The link is considered bad if error rate exceeds percentage. If check-error-percent is false, percentage is unused, and error percentage is not used as a detection method. percentage check-beacon A numeric value specifying the link error percentage The flag to indicate whether to enable this property to enable beacon probing as a method to validate the link status of a physical network adapter Valid values: true, false checkBeacon can be enabled only if the VirtualSwitch has been configured to use the beacon. Attempting to set checkBeacon on a PortGroup or VirtualSwitch that does not have beacon probing configured for the applicable VirtualSwitch results in an error. Specifies the active network adapters used for load balancing Indicates the standby network adapters used for failover The flag to indicate whether checksum offloading is supported Valid values: true, false
No Conditional
active-nic standby-nic csum-offload tcp-segmentation
No No No
The flag to indicate whether TCP segmentation offloading (TSO) is No supported Valid values: true, false The flag to indicate whether zero copy transmits are supported Valid values: true, false The average bandwidth in bits per second, if shaping is enabled on the port The maximum burst size allowed in bytes if shaping is enabled on the port The flag to indicate whether or not traffic shaper is enabled on the port Valid values: true, false The peak bandwidth during bursts in bits per second if traffic shaping is enabled on the port No No No No
zero-copy-xmit average-bandwidth burst-size enabled
peak-bandwidth
No
The following figure shows the sample for vswitch-list. XML sample for vswitch-list
<vswitch-list> <vswitch> <change-operation></change-operation> <name></name> <spec> <num-ports></num-ports> <policy> <security> <allow-promiscuous></allow-promiscuous> <mac-changes></mac-changes> <forged-transmits></forged-transmits> </security> <nic-teaming> <policy></policy> <reverse-policy></reverse-policy> <notify-switches></notify-switches> <rolling-order></rolling-order> <failure-criteria> <nic-order> <active-nic-list> <active-nic></active-nic> <active-nic></active-nic> </active-nic-list> <standby-nic-list> <standby-nic></stan dby-nic> <standby-nic></standby-nic> </standby-nic-list> </nic-order> </nic-teaming> <offload-policy> <csum-offload></csum-offload> <tcp-segmentation></tcp-segmentation> <zero-copy-xmit></zero-copy-xmit> </offload-policy> <shaping-policy> <enabled></enabled> <average-bandwidth></average-bandwidth> <peak-bandwidth></peak-bandwidth> <burst-size></burst-size> </shaping-policy> </policy> </spec> </vswitch> ... </vswitch-list>
entity-config
Specifies the configuration of the sub-entities such as a vApp container or a virtual machine The following table contains the definition for the child elements of entity-config. Child elements - entity-config
Element key
Definition Specifies the entity to power on or power off The key can be a virtual machine or a vApp. Valid value: String (name of a virtual machine or vApp)
Required No
start-action Specifies how to start the entity If this element is set to none, the entity does not participate in auto-start Valid values: none, powerOn start-delay Specifies the delay, in seconds, before continuing with the next entity in the order of entities to be started Valid value: Number Note This element is valid only if the entity is a virtual machine. start-order Specifies the start order for the entity Entities are started from lower numbers to highernumbers and in the reverse order during shutdown. Multiple entities with the same start order can be started in parallel and the order is unspecified. This value must be 0 or higher. Valid value: Number
No
No
No
stop-action Specifies the stop action for the entity If this element is set to none, the entity does not participate in auto-stop. Valid values: none, powerOff, guestShutdown, or suspend Note You can set the value of the <stop-action> element to guestShutdown and suspend, only if the entity is a virtual machine. stop-delay Specifies the delay, in seconds, before continuing with the next entity in the order sequence. Valid value: Number This element is valid only if the entity is a virtual machine and the <stop-action> element is set to guestShutdown. Specifies the tag for the entity Valid value: String
No
No Used only if the <stopAction> element is set to guestShutdown. No
tag
The following figure shows the sample for entity-config. XML sample for entity-config
<entity-config> <key></key> <start-action></start-action> <start-delay></start-delay> <start-order>/start-order> <stop-action></stop-action> <stop-delay></stop-delay> <tag></tag> </entity-config>
customization
Specifies the customization parameters for the guest operating system of the virtual machine. The following table describes for the child elements of customization. Child elements customization Element identity type Definition The network identity and settings, similar to Microsoft's Sysprep tool This element is a Sysprep, LinuxPrep, or SysprepText object. Valid values are: = CustomizationLinuxPrep CustomizationSysPrep The default value is CustomizationSysprep. Required No
password
Specifies the new administrator password for the virtual machine Sample format:
<password> <value></value> <plain-text></plain-text> </password>
No Valid only if the <identity-type> element is set to "CustomizationSysprep""
The value element contains the password string. The password is encrypted if the plain-text element is set to false. The plain-text element specifies whether the password is encrypted or plain text. Valid values of the plain-text element are: True False You can use the password element only if the following conditions are satisified: the OS password in the template is blank the CustomizationSysprep data object is used the password is used for auto logon purposes
time-zone
The time zone for the new virtual machine The numbers correspond to the time zones listed in the sysprep documentation on Microsoft Technet. Valid value: Integer
auto-logon
The flag that determines whether the machine automatically logs on No as Administrator Valid only if the Valid value: Boolean <identity-type> element is set to "CustomizationSysprep""
auto-logon-count If the AutoLogon flag is set, the AutoLogonCount property specifies the number of times the machine should automatically log on as Administrator.This value must be one. However, if your setup requires a number of reboots, you may need to increase it. This number may be determined by the list of commands executed by the GuiRunOnce command. Valid value: Integer full-name The full name of the user Valid value: String
Conditional Valid only if the <identity-type> element is set to "CustomizationSysprep"" Conditional Valid only if the <identity-type> element is set to "CustomizationSysprep"" Conditional Valid only if the <identity-type> element is set to "CustomizationSysprep"" No Valid only if the <identity-type> element is set to "CustomizationSysprep"" No Valid only if the <identity-type> element is set to "CustomizationSysprep"" No Valid only if the <identity-type> element is set to "CustomizationSysprep"" No Valid only if the <identity-type> element is set to "CustomizationSysprep"" Conditional Valid only if the <identity-type> element is set to "CustomizationLinuxPrep"
computer-name
The computer name of the Microsoft Windows virtual machine Sample format: <computer-name> <name></name> </computer-name> The name of the user's organization Valid value: String
org-name
product-id
Microsoft Sysprep requires that a valid serial number be included in the answer file when mini-setup runs. This serial number is ignored if the original guest operating system was installed using a volume-licensed CD. Valid value: String The workgroup that the virtual machine must join If this value is specified, the domain name and authentication fields must be empty. Valid value: String The licensing mode for the server Valid values: perSeat, perServer
join-workgroup
auto-mode
auto-users
This key is valid only if the value of the AutoMode element is PerServer. The integer value specifies the number of client licenses purchased for the VMware VirtualCenter server installed. Valid value: Integer The computer name of the virtual machine (not running on Windows) Sample format: <host-name> <name></name> </host-name>
host-name
domain
The fully qualified domain name Valid value: String
Conditional Valid only if the <identity-type> element is set to "CustomizationLinuxPrep"
dns-server-list
The list of DNS servers for a virtual network adapter with a static IP No address If this list is empty, the guest operating system uses a DHCP server to get its DNS server settings. These settings configure the virtual machine to use the specified DNS servers. These DNS server settings are listed in order of preference. If you specify this element, you need to set dnsFromDhcp to false. Sample format: <dns-server-list> <dns-server-list></dns-server-list> <dns-server-list></dns-server-list> </dns-server-list> The list of name resolution suffixes for the virtual network adapter No This list applies to both Windows and Linux guest customization. For Linux, this setting is global, whereas for Windows, this setting is listed for each adapter. Sample format: <dns-suffix-list> <dns-suffix-list></dns-suffix-list> <dns-suffix-list></dns-suffix-list> </dns-suffix-list> The specification to obtain a unique IP address for the virtual network adapter Valid values: CustomizationFixedIp CustomizationDhcpIpGenerator Sample format:
<ip type=""> <ipAddress></ipAddress> </ip>
dns-suffix-list
ip
No
subnet-mask gateway dns-domain
The subnet mask for the virtual network adapter Valid value: String For a virtual network adapter with a static IP address, this data object type contains a list of gateways, in order of preference. A DNS domain suffix such as vmware.com Valid value: String
No No No
The following figure shows the sample for customization. XML Sample for customization
<customization> <identity type="CustomizationSysprep"> <gui-unattended> <password> <value>abc123</value> <plain-text>true</plain-text> </password> <time-zone></time-zone> <auto-logon></auto-logon> <auto-logon-count></auto-logon-count> </gui-unattended> <user-data> <full-name></full-name> <org-name></org-name> <computer-name> <name>A</name> </computer-name> <product-id></product-id> </user-data> <identification> <join-workgroup></join-workgroup> </identification> <license-file-print-data> <auto-mode></auto-mode> <auto-users></auto-users> </license-file-print-data> <host-name> <name></name> </host-name> <domain></domain> </identity> <globalIPSettings> <dns-server-list> <dns-server-list></dns-server-list> <dns-server-list></dns-server-list> </dns-server-list> <dns-suffix-list> <dns-suffix-list></dns-suffix-list> <dns-suffix-list></dns-suffix-list> </dns-suffix-list> </globalIPSettings> <nic-setting-map> <adapter> <ip type="CustomizationDhcpIpGenerator"> <ipAddress></ipAddress> </ip> <subnet-mask></subnet-mask> <gateway></gateway> <dns-domain></dns-domain> </adapter> </nic-setting-map> <customization>
search-domain-list
Lists the domain in which to search for hosts. The following table contains the definition for the child elements of search-domain-list. Child elements -search-domain-list Element Definition Required No
search-domain The domain in which to search for hosts, placed in order of preference When DHCP is not enabled, the property can be set explicitly. When DHCP is enabled, the property reflects the current DNS configuration, but cannot be set.
The following figure shows the sample for search-domain-list. XML Sample for search-domain-list
<search-domain-list> <search-domain></search-domain> <search-domain></search-domain> <search-domain-list>
portgroup-list
The list of port groups configured on the host. The following table contains the definition for the child elements of portgroup-list. Child elements -portgroup-list Element change-operation Definition Indicates the change operation to apply on this configuration specification Valid values: add, edit, remove The name of the port group The VLAN ID for ports using this port group Example values: A value of 0 specifies that you do not want the port group associated with a VLAN A value from 1 to 4094 specifies a VLAN ID for the port group A value of 4095 specifies that the port group should use trunk mode, which allows the guest operating system to manage its own VLAN tags Required No
name vlan-id
No No
v-switch-name allow-promiscuous
The identifier of the virtual switch on which this port group is located The flag to indicate whether or not all traffic is seen on the port Valid values: true, false
No No
mac-changes
The flag to indicate whether the Media Access Control (MAC) address No can be changed Valid values: true, false The flag to indicate whether the virtual network adapter should be allowed to send network traffic with a different MAC address than that of the virtual network adapter Valid values: true, false Network adapter teaming policy includes failover and load balancing Valid values: loadbalance_ip: route based on ip hash loadbalance_srcmac: route based on source MAC hash loadbalance_srcid: route based on the source of the port ID failover_explicit: use explicit failover order No
forged-transmits
policy
Conditional The nic teaming policy tags are valid only if network adapter bridge is of type BondBridge.
reverse-policy
The flag to indicate whether the teaming policy is applied to inbound frames as well For example: if the policy is explicit failover, a broadcast request goes through uplink1 and comes back through uplink2. Then if the reverse policy is set, the frame is dropped when it is received from uplink2. This reverse policy is useful to prevent the virtual machine from getting reflections. Valid values: true, false The flag to specify whether to notify the physical switch if a link fails Valid values: true, false Note: If this property is true, ESX Server will respond to the failure by sending a RARP packet from a different physical adapter, causing the switch to update its cache.
No
notify-switches
No
rolling-order
The flag to indicate whether to use a rolling policy when restoring links No For example: If the explicit link order is (vmnic9, vmnic0), therefore vmnic9 goes down, vmnic0 comes up. However, when vmnic9 comes backup, if rollingOrder is set to be true, vmnic0 continues to be used, otherwise, vmnic9 is restored as specified in the explicitly order. Valid values: true, false
check-speed
The configured speed type to use when detecting link failure Valid values: exact: Use exact speed to detect link failure minimum: Use minimum speed to detect failure empty string: Do not use link speed to detect failure
No
speed check-duplex
A numeric value specifying the speed used to detect link failures The flag to indicate whether to use the link duplex reported by the driver as link selection criteria If check-duplex is true, then fullDuplex is the configured duplex mode. The link is considered bad if the link duplex reported by driver is not the same as fullDuplex. If check-duplex is false, then fullDuplex is unused, and link duplexity is not used as a detection method. Specifies using the link in duplex mode Valid values: true, false
No Yes
full-duplex
No
check-error-percent Indicates whether to use link error percentage to detect failure No Valid values: true, false If check-error-percent is true, the percentage is the configured error percentage that is tolerated. The link is considered bad if the error rate exceeds percentage. If check-error-percent is false, percentage is unused, and error percentage is not used as a detection method. percentage check-beacon A numeric value specifying the link error percentage The flag to indicate whether to enable this property to enable beacon probing as a method to validate the link status of a physical network adapter Valid values: true, false checkBeacon can be enabled only if the VirtualSwitch has been configured to use the beacon. Attempting to set checkBeacon on a PortGroup or VirtualSwitch that does not have beacon probing configured for the applicable VirtualSwitch results in an error. Specifies the active network adapters used for load balancing Indicates the standby network adapters used for failover The flag to indicate whether checksum offloading is supported Valid values: true, false The flag to indicate whether TCP segmentation offloading (TSO) is supported Valid values: true, false The flag to indicate whether zero copy transmits are supported Valid values: true, false The average bandwidth in bits per second, if shaping is enabled on the port The maximum burst size allowed in bytes if shaping is enabled on the port No Conditional
active-nic standby-nic csum-offload tcp-segmentation
No No No No
zero-copy-xmit average-bandwidth burst-size enabled
No No No
The flag to indicate whether or not traffic shaper is enabled on the port No Valid values: true, false
peak-bandwidth standby-nic
The peak bandwidth during bursts in bits per second if traffic shaping is enabled on the port Indicates the standby network adapters used for failover
No No
The following figure shows the sample for portgroup-list. XML Sample for portgroup-list
<portgroup-list> <portgroup> <change-operation></change-operation> <spec> <name></name> <vlan-id></vlan-id> <vswitch-name></vswitch-name> <policy> <security> <allow-promiscuous></allow-promiscuous> <mac-changes></mac-changes> <forged-transmits></forged-transmits> </security> <nic-teaming> <policy></policy> <reverse-policy></reverse-policy> <notify-switches></notify-switches> <rolling-order></rolling-order> <failure-criteria> <check-speed></check-speed> <speed></speed> <check-duplex></check-duplex> <full-duplex></full-duplex> <check-error-percent></check-error-percent> <percentage></percentage> <check-beacon></check-beacon> </failure-criteria> <nic-order> <active-nic-list> <active-nic></active-nic> <active-nic></active-nic> </active-nic-list> <standby-nic-list> <standby-nic></standby-nic> <standby-nic></standby-nic> </standby-nic-list> </nic-order> </nic-teaming> <offload-policy> <csum-offload></csum-offload> <tcp-segmentation></tcp-segmentation> <zero-copy-xmit></zero-copy-xmit> </offload-policy> <shaping-policy> <enabled></enabled> <average-bandwidth></average-bandwidth> <peak-bandwidth></peak-bandwidth> <burst-size></burst-size> </shaping-policy> </policy> </spec> </portgroup> ... </portgroup-list>
memory-allocation
Resource limits for memory. The following table contains the definition for the child elements of memory-allocation. Child elements -memory-allocation Element Definition Required Conditional Mandatory for the Create_VApp operation Conditional Mandatory for the Create_VApp operation
expandable-reservation In a resource pool with an expandable reservation, the reservation on a resource pool can grow beyond the specified value, if the parent resource pool has unreserved resources. A non-expandable reservation is called a fixed reservation. This property is ignored for virtual machines. Valid values: true, false reservation Amount of resource, in MB, that is guaranteed available to the virtual machine or resource pool Reserved resources are not wasted if they are not used. If the utilization is less than the reservation, the resources can be used by other running virtual machine. The memory space to be reserved should be less than the memory limit specified for the virtual machine. Valid value: number The limit of utilization, in MB, of a virtual machine resource pool The resource pool cannot exceed this limit, even if there are available resources. This is typically used to ensure a consistent performance of virtual machines and resource pools independent of available resources. If the limit element is set to -1, there is no fixed limit on resource usage. The limit is only bounded by available resources and shares. The number of shares allocated Used to determine resource allocation in case of resource contention. Only shares with custom values can be compared. There is no unit for this value. It is a relative measure based on the settings for other resource pools. This value is set only if the level element is set to custom. If level is not set to custom, this value is ignored. The allocation level The level is a simplified view of shares. Levels map to a pre-determined set of numeric values for shares. Valid values: custom - Shares are specified in the shares column high - Shares =Shares = 20 * virtual machine memory size in megabytes low - Shares = 5 * virtual machine memory size in megabytes normal - Shares = 10 * virtual machine memory size in megabytes If the shares value does not map to a predefined size, the level is set as custom.
limit
Conditional Mandatory for the Create_VApp operation Conditional Mandatory for the Create_VApp operation Conditional Mandatory for the Create_VApp operation
shares
level
The following figure shows the sample for memory-allocation. XML Sample for memory-allocation
<memory-allocation> <expandable-reservation></expandable-reservation> <reservation></reservation> <limit></limit> <shares> <shares></shares> <level></level> </shares> </memory-allocation>
connectable
Specifies the connection properties of a device. The following table contains the definition for the child elements of connectable. Child elements - connectable Element start-connected Definition Flag to specify whether or not to connect the device when the virtual machine starts Required No No No
allow-guest-control Flag to allow the guest to control whether the connectable device is connected connected Flag indicating the device is currently connected This flag is valid only while the virtual machine is running.
The following figure shows the sample for connectable. XML sample for connectable
<connectable> <start-connected></start-connected> <allow-guest-control></allow-guest-control> <connected></connected> </connectable>
tools
The configuration of VMware tools running on the guest operating system. The following table contains the definition for the child elements of tools. Child elements - tools Element tools-version Definition the version of VMware Tools installed on the guest operating system valid value: String Required No
after-power-on
the flag to specify whether the scripts should run after the virtual machine powers on valid values: true, false the flag to specify whether the scripts should run after the virtual machine resumes valid values: true, false the flag to specify whether the scripts should run before the virtual machine suspends valid values: true, false the flag to specify whether the scripts should run before the virtual machine reboots valid values: true, false
No
after-resume
No
before-guest -standby
No
before-guest -reboot
No
before-guest-shutdown the flag to specify whether the scripts should run before the virtual machine powers off valid values: true, false
No
The following figure shows the sample for tools. XML Sample for tools
<tools> <tools-version></tools-version> <after-power-on></after-power-on> <after-resume></after-resume> <before-guest-standby></before-guest-standby> <before-guest-shutdown></before-guest-shutdown> <before-guest-reboot></before-guest-reboot> </tools>
power-op-info
Specifies the configuration for default power operations. These settings are advisory and clients can choose to ignore it. The following table contains the definition for the child elements of power-op-info. Child elements -power-op-info Element power-off-type Definition describes the default power off type for the virtual machine The possible values are specified by the PowerOpType. Valid values: hard - Perform power off by using the PowerOff method soft - Perform power off by using the ShutdownGuest method preset - The preset value is specified in the defaultPowerOffType section Required No
suspend-type
describes the default suspend type for the virtual machine The possible values are specified by the PowerOpType. Valid values: hard - Perform suspend by using the Suspend method soft - Perform suspend by using the StandbyGuest method preset - The preset value is specified in the defaultSuspendType section
No
reset-type
describes the default reset type for the virtual machine The possible values are specified by the PowerOpType. Valid values: hard - Perform reset by using the Reset method soft - Perform reset by using the RebootGuest method preset - The preset value is specified in the defaultResetType section
No
default-power-off-type the default operation for power off Valid values: soft, hard default-suspend-type default-reset-type standby-action specifies the default operation for suspend Valid values: soft, hard Specifies the default operation for reset Valid values: soft, hard Specifies the behavior of virtual machine when it receives the S1 ACPI call
No No No No
The following figure shows the sample for power-op-info. XML Sample for power-op-info
<power-op-info> <power-off-type></power-off-type> <suspend-type></suspend-type> <reset-type></reset-type> <default-power-off-type></default-power-off-type> <default-suspend-type></default-suspend-type> <default-reset-type></default-reset-type> <standby-action></standby-action> </power-op-info>
console-preferences
Preferences for the legacy console application that affect the way the application behaves during power operations on the virtual machine. The following table contains the definition for the child elements of console-preferences. Child elements -console-preferences Element Definition Required
power-on-when-opened
power on the virtual machine when it is opened in the console valid values: true, false
No No No
enter-full-screen-on-power-on go to full screen mode when the virtual machine is powered on valid values: true, false close-on-power off-or-suspend close the console application when the virtual machine is powered off or suspended valid values: true, false
The following figure shows the sample for console-preferences. XML Sample for console-preferences
<console-preferences> <power-on-when-opened></power-on-when-opened> <enter-full-screen-on-power-on></enter-full-screen-on-power-on> <close-on-power-off-or-suspend></close-on-power-off-or-suspend> </console-preferences>
flags
Encapsulates the flag settings for a virtual machine. The following table contains the definition for the child elements of flags. Child elements -flags Element Definition Required No No No No No
disable-acceleration the flag to turn off video acceleration for a virtual machine console window valid values: true, false enable-logging use-toe the flag to enable logging for a virtual machine valid values: true, false the flag to specify whether or not to use TOE (TCP/IP Offloading) valid values: true, false
run-with-debug- info the flag to specify whether or not to run in debug mode valid values: true, false ht-sharing Specifies how the Virtual CPUs of a virtual machine are allowed to share physical cores on a hyper-threaded system Valid values: any, internal, none Note: Two Virtual CPUs are sharing a core if they are both running on logical CPUs of the core at the same time.
The following figure shows the sample for flags. XML Sample for flags
<flags> <disable-acceleration></disable-acceleration> <enable-logging></enable-logging> <use-toe></use-toe> <run-with-debug-info></run-with-debug-info> <ht-sharing></ht-sharing> </flags>
Adding an SSL certificate

The following topic provides information about adding an SSL certificate to the peer keystore.
Adding an SSL certificate to the peer keystore

For the VMware adapter to function properly, you must add an SSL certificate to the keystore of the BMC Atrium Orchestrator peer, on which the adapter is enabled. The cacerts file in the JAVA_HOME/jre/lib/security/ folder contains the client certificate authority for the Java Virtual Machine (JVM). Only a root or an admin user can update the cacerts file. To install the SSL certificate, open a command-line shell and navigate to the folder containing the vcenter.cer file and execute the following command:
keytool -importcert -alias _alias name_ -file _certificate file name_ -keystore _location of keystore_
The following code snippet shows an example for installing the certificate.
_keytool -importcert -alias VMWARE -file vcenter.cer -keystore C:\Program Files\Java\jre6\lib\security\cacerts_
Troubleshooting
This section includes troubleshooting information that is generic, applicable to all the adapters and troubleshooting specific to certain application adapters.
Generic adapter troubleshooting

This section provides information about general troubleshooting steps for an adapter: Adapter troubleshooting steps Debug-level adapter logging
Adapter troubleshooting steps

The general troubleshooting steps for an adapter are: 1.
1. Check the processes.log files for messages returned by the adapter. BMC Atrium Orchestrator uses two processes.log files, one processes.log file for the grid and the other processes.log file for the BMC Atrium Orchestrator Development Studio. 2. If a workflow is executed on the grid, the adapter requests and responses are logged in the processes.log file and the grid.log file for the grid. If a workflow is executed on the grid using a rule or a schedule, the entire wrapper-related information is logged in the processes.log file and the grid.log file for the grid. The processes.log file also contains any debug messages associated with the workflow. 3. If a workflow is executed from the BMC Atrium Orchestrator Development Studio, the adapter requests and responses are logged in the processes.log file for the BMC Atrium Orchestrator Development Studio. Note The processes.log file for the grid is located in the AO_HOME\tomcat\logs directory and the processes.log file for the BMC Atrium Orchestrator Development Studio is located in the AO_HOME\Studio\logs directory. AO_HOME refers to the directory in which BMC Atrium Orchestrator is installed. 4. Check the grid.log file on the peer for java exceptions. Verify whether the java exception is known and if a resolution exists. Note The grid.log file is located in the AO_HOME\tomcat\logs directory. 5. Verify that the adapter configuration in Grid Manager is correct. 6. If none of the above steps help in identifying or resolving the issue, verify that the adapter can connect to the ports used by the target application. For verifying connectivity, you can execute telnet, ping, or traceroute commands. If the connectivity does not exist, check whether the ports of the target application are blocked.
Debug-level adapter logging

If none of the general adapter troubleshooting steps help you in identifying or solving the issue, you need to enable debug-level adapter logging and open a customer support ticket via the BMC Support web interface, with the logging information specified in the ticket.
To enable debug-level adapter logging

1. 2. 3. 4. 5. Log on to Grid Manager. Click the Manage tab, and click the Peers tab. From the currently defined peers for the grid, select the peer on which the adapter is enabled, and click Edit. On the Edit a Peer Configuration page, click Configure Logging. On the Edit Logging Levels on Peer page, set the Logging Level to DEBUG for Adapter Framework, Adapters, Library Manager and Configuration. Adapter debug provides logging information about adapter actions involved in executing an adapter request. Adapter Framework and Library Manager debug provides logging information about the success or failure of configuring an adapter or enabling an adapter on the peer. Configuration debug enables you to verify whether the adapter configuration is correct. 6. Click OK. 7. Click OK on the Edit a Peer Configuration page. You can duplicate the error that occurred previously and obtain the debug-level logging information for the error from the grid.log file.
To open a support ticket

1.
1. Log on to the Customer support application via the web interface at http://apps.bmc.com/server/available.cfm?fc=REMSUBMITCASE. 2. Create a ticket and include the debug-level logging information in the ticket.
Known issues and workarounds

The following issues remain open in this release. Known issues in 20.11.02 content release Support ID Tracking ID Description Installation issues None INSTALL-1288 When you execute the BMC Atrium Orchestrator content installation program repetitively, the installation program does not display the Installation Type panel, on which you select BSM Solutions. Instead, the installation program proceeds with the installation and then fails with the Remedy ITSM error message. Workaround: 1. Navigate to the directory in which the BMC Atrium Orchestrator content is installed. 2. Delete the ContentInstalledConfiguration.xml file located in the directory in which the BMC Atrium Orchestrator content is installed. 3. Rerun the content installation program. Upgrade issues None AMP-17521 / If you upgrade the configuration of an adapter that was configured using the XML INSTALL-4971 view to a newer configuration by using the form view using Upgrade Adapters on Grid in Grid Manager, the adapter configuration is lost. When you try to modify the configuration, the form view displays an empty form. Also, when you click Switch to XML View, Properties contains an empty <config> element. None AMP-17536 / The BMC Atrium Orchestrator Application Adapter for VMware Infrastructure, which INSTALL-1316 requires a certificate, does not work when you upgrade from platform version 7.6.01.04 to 7.6.02. See Known issues and workarounds for details. BMC Remedy AR System adapter issues None ADAPTER-4397 For create, delete, and update operations, if the input parameter version is not 7.0 or 7.5, the adapter response terminates without displaying an appropriate error message. None ADAPTER-4399 The responses for the Delete Items and Delete Entry operations are not displayed on the console window. ISS03722504 ADAPTER-4588 The monitor adapter fails to pick up new alerts upon initialization. VMware Infrastructure adapter issues ISS03621008 ADAPTER-2639 The workflows that create a VM ignore the folder where the VM is created even if you provide the folder name in the <folder> element. None ADAPTER-4384 The Update_CD_ROM_Configuration operation does not update any of the following elements within the <connectable> element: <start-connected> <allow-guest-control> <connected> None None None ADAPTER-4642 The Create_VApp operation does not create a vApp under a resource pool where the resource pool exists under a vApp. ADAPTER-4726 For the Update Hard Disk operation, you must specify <shares>, an optional element if you specify the <level> element in the request. ADAPTER-4960 All the certificates are not removed from the cacerts file when you disable the
adapter that is enabled using multiple targets. Solaris Zones adapter issues None ADAPTER-4901 For the Create Zone With Custom Settings operation, you must specify the <address> element, a child element of the <network-interface> element, when you specify the <network-interface> element in the request. You should not have to specify this element. None ADAPTER-4902 For the Create Zone With Custom Settings operation, the value of the <inherit-pkg> element specified in the adapter request is not reflected in the created zone. None ADAPTER-4913 For the Update Zone Configuration operation, if you specify an exclusive value for the <ip-type> element and a value for the <physical> attribute only, you cannot remove or update the network interface. None ADAPTER-4914 For the Update Zone Configuration operation, the <inherit-packages> element does not work as designed when you add, remove, or update a zone. BMC BladeLogic Server Automation adapter issues None ADAPTER-4286 With version 8.0 (SP4) and later releases of the BMC BladeLogic Server Automation application, the adapter does not select the correct executable with the desired extension and displays the Could not find jvm_path message. Workaround: 1. Create a system variable named NSHDIR and set its value to C:\Program Files\BMC Software\BladeLogic\8.0\NSH. 2. Add %NSHDIR%\bin to the system's path variable (if it does not already exist). 3. Restart the CDP server. None ADAPTER-4321 Multiple spaces provided in NSH script arguments are replaced by a single space in the adapter response. Workaround: Declare the script variables in double quotes to preserve multiple spaces. For example, if you specify echo "a3:" "$3" instead of echo "a3:" $3 in the script, the output displays the arguments with the correct number of spaces. None ADAPTER-4322 The nexec command does not correctly handle NSH scripts with arguments that have empty values when executed on a remote computer. Workaround: When executing NSH scripts on a remote computer, specify arguments that have empty values as single quotes within double quotes ("''"). None ADAPTER-4323 A single NSH script or command executed on a 64-bit computer opens multiple sessions. None ADAPTER-4324 The <exit-code> and <status> elements are incorrectly set for Jython scripts in the adapter response. None ADAPTER-4325 NSH commands do not execute correctly when the <timeout-secs> element specified in the configuration or request is equal to the command execution time. None ADAPTER-4704 If the arguments for a script have leading or trailing spaces for multiple arguments, the spaces are not retained in the response for all the arguments. However, for a single argument, spaces are retained. Microsoft Exchange 2007 adapter issues None ADAPTER-3376 The Get Message operation does not support the <recipientsinfo> element because the value of this element is first stored in a variable and then extracted to display information about recipients. None ADAPTER-3380 You must specify the <name> element within the <parameter> element to execute adapter requests. If you specify only the <value> element without the <parameter> element, the adapter does not use the <value> element because it does not support positional parameters. None ADAPTER-3381 The Get Distribution Group Member operation does not support the <credential> element. None ADAPTER-3382 The <server> element is required for the New Receive Connector operation
when the Microsoft Exchange server is installed on a 32-bit computer. ADAPTER-3386 If you specify the distinguished name within single quotes in adapter requests, an error message is displayed. None ADAPTER-3393 The <RecipientFilter> element in the Set Dynamic Distribution Group operation does not work. None ADAPTER-3395 The <SourceTransportServers> element is required in the New Send Connector operation to define a send connector. None ADAPTER-3397 If you specify invalid values for the Target Os Bit Version and Timeout Secs fields when you use the form view to configure the Microsoft Exchange 2007 adapter, an error message is displayed intermittently, and the configuration is saved. None ADAPTER-3403 The <LogFolderPath> element is required in the New Storage Group operation when the Microsoft Exchange server is installed on a different 64-bit computer. None ADAPTER-3405 You must specify the <Enabled> element when you set the <Force> element to $true in the Set Send Connector operation. None ADAPTER-3408 You must specify the distinguished name without any quotes (single or double) in the Enable Mail Contact operation. Microsoft Exchange 2003 adapter issues None ADAPTER-3404 The Delete-All-Messages-In-Queue operation response displays error messages intermittently. None ADAPTER-3407 If you specify an invalid value for the Timeout Secs field when you use the form view to configure the adapter, an error message is displayed intermittently, and the configuration is saved. None ADAPTER-3409 If you specify an incorrect <DomainName> element in the Move User Mailbox operation request, an error message is displayed. Amazon EC2 adapter issues None ADAPTER-1368 The revoke-security-group-ingress operation response displays success when the <items> XML element contains a permission that is not a part of the specified security group or is already revoked. None ADAPTER-1370 For the bundle-instance operation, if you specify an incorrect value for the <aws-access-key-id> element, the bundle task starts, but does not complete. The Incorrect access key specified message is displayed. You observe similar behavior when you specify incorrect values for the following elements: None <secret-access-key> <bucket> <prefix> None None None None None None None ADAPTER-1371 The register-image operation does not add root device and block device mapping information to the Amazon Machine Image (AMI). ADAPTER-1374 The describe-image-attribute operation response does not retrieve kernel, ramdisk, and block-device-mapping information of the created image. ADAPTER-1378 The <groups> element in the authorize-security-group-ingress operation request does not work. ADAPTER-1379 The delete-key-pair operation response displays success when you specify a nonexistent key pair in the request. ADAPTER-1380 The describe-image-attribute operation displays success when you specify more than one conditional parameter. ADAPTER-1382 The detach-volume operation request containing the <force> element accepts invalid values and successfully detaches the volume from the specified instance. ADAPTER-1383 The describe-images operation response does not display information about the images when <executable-by-set>, <owners-set>, and <images-set> elements are present in the request. ADAPTER-1388 The <no-device> element in the run-instances operation request does not work.
None
None
ADAPTER-1398 The < block-device-mapping> element in the modify-instance-attribute operation request does not work. BMC Event Manager and BMC ProactiveNet Performance Manager adapter issues None ADAPTER-1679 The adapter displays a wrong error message when you specify a large numeric value as an input for the Port Number field. None ADAPTER-1733 If the cell stops before executing the set-action-result operation request, the cell loses its action-result-id state. When the cell restarts, the request reaches the cell after being buffered. Therefore, the cell does not identify the action-result-id and generates an error response. None ADAPTER-1756 The adapter restricts you from applying any filter criteria (for example, greater_than, less_than, not_equals, and so on) against the unlisted slots. VMware vCloud adapter issues None ADAPTER-4351 The adapter response does not contain the <status> element when a required element is missing from the adapter request. None ADAPTER-4436 The Power_Off_vApp operation partially powers off the VMs contained in the vApp. None ADAPTER-4441 The Clone_vApp operation does not work when the <deploy> and <power-on> elements are set to true. None ADAPTER-4463 The Compose_vApp operation does not work when the request contains child elements which in turn have the same child names. For example, compose a vApp, TestUser, which contains vApp1 as <vapp-id> and TestTemplate as <vapp-template>. If vApp1 has a VM named Test1 and TestTemplate creates a VM called Test1, the adapter tries to compose a vApp having two instances of Test1 and the request fails. None ADAPTER-4611 The Add Organization Network operation does not use the value specified in the <is-inherited> element. For example, if you specify <is-inherited>true</is-inherited> for an isolated network, the network is created but the value of <is-inherited> is false. Also, if you specify <is-inherited>false</is-inherited> for a bridged network, the network is created but the value of <is-inherited> is true. None ADAPTER-4612 The Add Organization Network operation does not create a NAT-routed network. However, the adapter response shows successful execution. None ADAPTER-4621 The Add Organization Network operation does not add multiple IP ranges when creating a new network. None ADAPTER-4623 The Modify Organization Network operation displays Cannot update-undeploy the network first when you update the network's fence mode. None ADAPTER-4624 The Modify Organization Network operation does not update the modified network with the value specified in the <network-pool-id> element. A similar issue occurs with the <parent-network-id> element for a bridged network. None ADAPTER-4662 The Create Organization operation does not support MD5DIGEST and NTLM values for the <authentication-mechanism> element. None ADAPTER-4663 The Create Organization operation does not add the following elements specified in the adapter request to the newly created organization: <back-linkidentifier> <realm> <alert-email-to> None ADAPTER-4673 The Create Organization operation does not allow you to specify the SMTP server port. None ADAPTER-4717 The <vm-startup-details> element does not work when the vApp template is specified in the Compose_vApp operation. VMware Lifecycle Manager adapter issues None ADAPTER-2562 In the BMC Atrium Orchestrator Application Adapter for VMware Lifecycle Manager
User Guide information for the Apply Placement operation, the <comment> element is incorrectly marked as required. This element is optional. None ADAPTER-2564 In the BMC Atrium Orchestrator Application Adapter for VMware Lifecycle Manager User Guide information for the Apply Placement operation, the <shapingTemplate> element is incorrectly marked as required. This element is optional. None ADAPTER-2566 In the BMC Atrium Orchestrator Application Adapter for VMware Lifecycle Manager User Guide information for the Request Virtual Machine operation, the <groupControl> and <groupView> elements are incorrectly marked as required. These elements are optional. Service-now adapter issues ISS03659129 ADAPTER-4296 The adapter cannot handle complex target URLs (for example, abc/xyz). IBM Tivoli Storage Manager adapter issues None ADAPTER-363 The following operations do not work on the Linux OS: Preview Archive Preview Backup Delete Access Delete Filespace Microsoft System Center Configuration Manager adapter issues None BMCCAT-2684 The actor and monitor adapters cannot be enabled on a peer installed on the same computer as the Microsoft System Center Configuration Manager application. Amazon S3 adapter issues None ADAPTER-4794 The List Bucket operation <prefix> element limits searching and filtering to only the topmost level in the bucket. None ADAPTER-4787 The Create Bucket operation does not support the valid regions specified in the <endpoint-address> element. Instead, all the buckets are created with US Standard, the default region.
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.
Support website
You can obtain technical support from BMC at http://www.bmc.com/support. From this website, you can: Read overviews about the different levels of support services and other programs that BMC offers Find current information about BMC products Search the knowledge base for issues similar to yours and possible solutions, or for articles about the product 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 customer_support@bmc.com. (In the subject line, enter SupID:
yourSupportContractID, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Copyright 2011 BladeLogic, 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. BladeLogic and the BladeLogic logo are the exclusive properties of BladeLogic, Inc. The BladeLogic trademark is registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BladeLogic trademarks, servicemarks, 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, Netcool, and Tivoli are registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Linux is the registered trademark of Linus Torvalds. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners UNIX is the registered trademark of The Open Group in the US and other countries. 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. BMC SOFTWARE INC 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA 713 918 8800 Customer Support: 800 537 1813 (United States and Canada) or contact your local support center
Additional resources
The following hyperlinks provide information outside of the BMC Atrium Orchestrator content version 20.11.02 documentation that you might find helpful: BMC Communities, BMC Atrium Orchestrator community is a resource where people who leverage BMC technology can find assistance in building solutions that solve critical business problems. Search the BMC Support Knowledge Base filtered by BMC Atrium Orchestrator BMC Educational Services, BMC Atrium Orchestrator learning path www.bmc.com for information about BMC Atrium Orchestrator BMC Global Services, http://www.bmc.com/solutions/services/global-services-main.html

BAO 20.11.02 Application Adapters Space

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

BAO 20.11.02 Application Adapters Space

Transféré par

Droits d'auteur :

Formats disponibles

Copyright 2009 -- 2011 BladeLogic, Inc.

BMC Atrium Orchestrator Application Adapters 20.11.02

BMC Atrium Orchestrator Application Adapters 20.11.02

About BMC Atrium Orchestrator adapters

BMC Atrium Orchestrator Application Adapters 20.11.02

Recently updated pages

December Documentation updates for 12, 2011 December 12, 2011

License entitlements for BMC Atrium Orchestrator Application Adapters

BMC Atrium Orchestrator Application Adapters 20.11.02

BMC Atrium Orchestrator - Adapter License Add-on

BMC Atrium Orchestrator Application Adapters

BMC Atrium Orchestrator for Network Automation - Application Adapters

BMC Atrium Orchestrator for Server Automation - Application Adapters

Enhancements in version 20.11.02

BMC Atrium Orchestrator Application Adapters 20.11.02

Introducing the BMC Atrium Orchestrator Application Adapter for Amazon S3

BMC Atrium Orchestrator Application Adapters 20.11.02

Changes to BMC Atrium Orchestrator Application Adapter for VMware Infrastructure

BMC Atrium Orchestrator Application Adapters 20.11.02

Changes to BMC Atrium Orchestrator Application Adapter for Amazon EC2

Changes to BMC Atrium Orchestrator Application Adapter for HP Operations Manager

Changes to BMC Atrium Orchestrator Application Adapter for HP Service Manager

BMC Atrium Orchestrator Application Adapters 20.11.02

Changes to BMC Atrium Orchestrator Application Adapter for Service-now

Corrected problems in version 20.11.02

BMC Atrium Orchestrator Application Adapters 20.11.02

Documentation updates for December 12, 2011

BMC Atrium Orchestrator Application Adapters 20.11.02

BMC Atrium Orchestrator Application Adapters 20.11.02

Adapter module lifecycle

BMC Atrium Orchestrator Application Adapters 20.11.02

BMC Atrium Orchestrator Application Adapters 20.11.02

Enabling an adapter on a peer

Enable adapter on at least one peer on the grid

To enable an adapter on a peer

Exporting the adapter module to the repository

BMC Atrium Orchestrator Application Adapters 20.11.02

from BMC Atrium Orchestrator Development Studio to the repository.

To export the adapter module to the repository

Activating a module on the grid manager

BMC Atrium Orchestrator Application Adapters 20.11.02

Recommended installation environment

BSM Solutions installation path

Custom feature set installation path

BMC Atrium Orchestrator Application Adapters 20.11.02

Using the GUI to install BMC Atrium Orchestrator content

Before you begin

To install BMC Atrium Orchestrator content with the GUI installation

BMC Atrium Orchestrator Application Adapters 20.11.02

Using command-line options to install BMC Atrium Orchestrator content

Silent installation properties

BMC Atrium Orchestrator Application Adapters 20.11.02

Installation properties for content options files

BMC Atrium Orchestrator Application Adapters 20.11.02

AO_REPOSITORY_USER_NAME Specifies the user name required to log on -J AO_REPOSITORY_USER_NAME=admin

BMC Atrium Orchestrator Application Adapters 20.11.02

Sample content options file templates

Options file to install all content

Options file to install all base adapters

Options file to install selected base adapters

BMC Atrium Orchestrator Application Adapters 20.11.02

Options file to install all application adapters

Options file to install selected adapters