BMC Atrium Orchestrator User Guide

for Base Adapters

Supporting
BMC Atrium Orchestrator version 7.6.05.00 Base Adapters
December 2010

www.bmc.com

Contacting BMC Software

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

United States and Canada

Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000

Outside United States and Canada

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

Copyright 2009-2010 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, Inc. considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and the proprietary and restricted rights notices included in this documentation. IBM is the trademark or registered trademark of International Business Machines Corporation in the United States, other countries, or both. 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. Linux is the registered trademark of Linus Torvalds.

Restricted rights legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 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 must be sent to this address.

Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or email. To expedite your inquiry, see Before contacting BMC.

Support website
You can obtain technical support from BMC at http://www.bmc.com/support. From this website, you can:
s s s s s s s s

Read overviews about the several 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 email alerts when new product notices are released Find worldwide BMC support center locations and contact information, including email addresses, fax numbers, and telephone numbers

Support by telephone or email

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 email message to customer_support@bmc.com. (In the subject line, enter SupID:<yourSupportContractID>, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC

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

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

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

s s s

sequence of events leading to the issue commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software

License key and password information

If you have questions about your license key or password, contact BMC as follows:
s

(USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an email message to ContractsPasswordAdministration@bmc.com. (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an email message to password@bmc.com. (Asia-Pacific) Contact your BMC sales representative or your local BMC office.

BMC Atrium Orchestrator Base Adapters User Guide

Contents
About this book 9 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Searching across PDF documents in a folder and its subfolders . . . . . . . . . . . . . . . . . 10 Chapter 1 Overview of base adapters 13 13 14 16 20 21 23 24 25 26 27 27 30 30 31 31 32 32 33 34 35 36 37 38 38 39 39 40 43

Adapter overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Actor adapter requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Actor adapter responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitor adapter events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Terminal adapter features

Multiple configuration nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attributes for specifying directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attribute for specifying a timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FAT commands to enable platform independence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attribute for continuing execution after a command failure . . . . . . . . . . . Command attribute for disabling line-termination character . . . . . . . . . . . . . . . . . . . . Command attribute for ignoring a command response. . . . . . . . . . . . . . . . . . . . . . . . . Command attribute for using a special character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistent connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Proxy commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Known hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Public key authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verification of OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . env-variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . executable directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminal adapters feature overview table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Using Terminal adapters

File adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Contents

File adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 File adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 File adapter request with read action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 File adapter response with read action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 File adapter request with write action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 File adapter response with write action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 File adapter request with append action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 File adapter response with append action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 File adapter request with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 File adapter response with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Command Line adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Command Line adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Command Line adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Command Line adapter requestUNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Command Line adapter requestMicrosoft Windows . . . . . . . . . . . . . . . . . . . . . . 63 Command Line adapter responseWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Session-based CLI adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Windows Session-based CLI adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . 74 UNIX Session-based CLI adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Session-based CLI adapter requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . 77 run-as support in Command Line adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 SSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 SSH adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 SSH adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 SSH adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 SSH adapter keyboard-interactive capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 SSH KBI adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 SSH KBI adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 SSH KBI adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Kerberized SSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Kerberized SSH adapter (Java client)adapter configuration . . . . . . . . . . . . . . . 119 Kerberized SSH adapter (Java client)adapter request . . . . . . . . . . . . . . . . . . . . 122 Kerberized SSH adapter (Java client)adapter response . . . . . . . . . . . . . . . . . . . 125 Kerberized SSH adapter (local client)adapter configuration. . . . . . . . . . . . . . . 129 Kerberized SSH adapter (local client)adapter request . . . . . . . . . . . . . . . . . . . . 131 Kerberized SSH adapter (local client)adapter response. . . . . . . . . . . . . . . . . . . 135 Telnet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Telnet adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Telnet adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Telnet adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SCP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 SCP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 SCP adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SCP adapter request with get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SCP adapter response with get action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 SCP adapter request with put action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 SCP adapter response with put action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 FTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 FTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Book Title

FTP adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with a dynamic target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with a dynamic target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with append command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with append command . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with cdup command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with cdup command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with mode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with mode command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with put command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with rmdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with rmdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with stat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with stat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter request with multiple commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP adapter response with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chgrp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chgrp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chmod command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chmod command . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chown command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chown command. . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with get-dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with get-dir command. . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with lcd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with lcd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with lpwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

167 168 168 169 171 172 174 176 177 179 180 182 183 186 188 190 191 193 194 196 197 199 201 203 204 206 207 209 211 212 213 216 217 221 222 225 226 230 231 235 236 240 241 245 246 250 251 255 256

Contents

SFTP adapter response with lpwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 SFTP adapter request with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 SFTP adapter response with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 SFTP adapter request with mkdir command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 SFTP adapter response with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 SFTP adapter request with mkdirs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 SFTP adapter response with mkdirs command . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 SFTP adapter request with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 SFTP adapter response with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 SFTP adapter request with put-dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 SFTP adapter response with put-dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 SFTP adapter request with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 SFTP adapter response with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 SFTP adapter request with rename command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 SFTP adapter response with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 SFTP adapter request with rm command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 SFTP adapter response with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 SFTP adapter request with symlink command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 SFTP adapter response with symlink command. . . . . . . . . . . . . . . . . . . . . . . . . . . 306 SFTP adapter request with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 SFTP adapter response with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . 308 Windows Command adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Windows Command adapter post-installation steps . . . . . . . . . . . . . . . . . . . . . . . 313 Windows Command adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Windows Command adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Windows Command adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 PowerShell adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 PowerShell adapter post-installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 PowerShell adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 PowerShell adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 PowerShell adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Chapter 4 Additional base adapters 335

HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 HTTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 HTTP adapter request with a get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 HTTP adapter response to a request with get action . . . . . . . . . . . . . . . . . . . . . . . 341 HTTP adapter request with a post action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 HTTP adapter response with post action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 HTTP adapter request with put action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 HTTP adapter response with put action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 HTTP adapter request with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 HTTP adapter response with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 Specifying header fields in the HTTP adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 JMS adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Prerequisites for the JMS adapter with IBM WebSphere MQ . . . . . . . . . . . . . . . . 358 JMS actor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 JMS monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Script adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
4 Book Title

Script adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Script adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 Script adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 SNMP actor adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 SNMP actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 SNMP actor adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 SNMP actor adapter request with get action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 SNMP actor adapter response with get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 SNMP actor adapter request with notification action . . . . . . . . . . . . . . . . . . . . . . 389 SNMP actor adapter response with notification action . . . . . . . . . . . . . . . . . . . . . 393 SNMP monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 SNMP monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 SNMP monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 SQL actor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 IMW Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 SQL actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 SQL actor adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 SQL actor adapter requestStandard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 SQL actor adapter responseStandard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 SQL actor adapter requestParameterized Statement . . . . . . . . . . . . . . . . . . . . . 411 SQL actor adapter responseParameterized Statement. . . . . . . . . . . . . . . . . . . . 416 Oracle XMLType data type support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Installing JDBC OCI Instant Client Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 SQL monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 SQL monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 SQL monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 SQL adapter FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Web Services adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Web Services adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Web Services adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Web Services adapter requestmethod one. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Web Services adapter responsemethod one . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Web Services adapter requestmethod two . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Web Services adapter responsemethod two . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Web Services adapter requestJAX-WS Approach . . . . . . . . . . . . . . . . . . . . . . . 455 Web Services adapter request for Make SOAP RequestPayload mode . . . . . 455 Web Services adapter response for Make SOAP RequestPayload mode . . . . 456 Web Services adapter request for Make SOAP RequestMessage mode . . . . . 458 Web Services adapter response for Make SOAP RequestMessage mode . . . . 465 Web Services adapter request for Poll Asynchronous Response . . . . . . . . . . . . . 467 Web Services adapter response for a request with Poll Asynchronous Response . 468 Differences in the methods used to define a Web Services adapter request . . . 469 Chapter 5 Mail adapters 471 471 472 472 477
5

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

SMTP adapter response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 IMAP mail adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 IMAP mail configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 IMAP mail monitor event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 POP mail adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 POP mail adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 POP mail event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 Chapter 6 Adapter utilities module 501

Overview of the OA Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Common. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Invoke SOAP request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Email SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Send Email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 HTTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Send Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 Send Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 PowerShell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 Ad Hoc Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Ad Hoc Update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Parameterized Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 Terminal File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Write. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Terminal FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 cdup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 put. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
6 Book Title

rm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Terminal SCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Terminal SFTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 chgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 chown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 get-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 lcd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 lpwd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 mkdirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 put dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 rename. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 rm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 symlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Terminal Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Terminal SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Terminal Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Terminal Kerberos ticket properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Terminal Kerberos SSH1 adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Terminal Kerberos SSH1 adapter configuration with valid TGT specified . . . . 609 Terminal Kerberos SSH1 adapter configuration with dynamic targets . . . . . . . 610 Terminal Kerberos SSH2 adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Terminal Kerberos SSH2 adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Terminal Kerberos SSH2 adapter configuration with krb-realm . . . . . . . . . . . . . 614 Terminal Kerberos SSH2 adapter configuration elements . . . . . . . . . . . . . . . . . . 614 Terminal Kerberos SSH2 adapter configuration with dynamic targets . . . . . . . 615 Terminal Kerberos SSH2 adapter configuration elements with dynamic targets . . 617 Terminal Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Terminal Windows Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Make SOAP requestmethod one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Make SOAP requestmethod two. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 Appendix A Troubleshooting 627

Adapter troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 Debug-level adapter logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

Contents

Appendix B Appendix C Appendix D Index

Using ActivePerl scripts in a Windows environment Using IMW for SQL actor adapter operations Creating adapter modules using the Web Services base adapter

631 633 643 651

Book Title

Figures
XML sample of an adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of an adapter configuration with multiple nodes . . . . . . . . . . . . . . . . . . XML sample of a specific target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of all defined targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a dynamic target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of <command> attributes for directories . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a command attribute for timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a FAT command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a multi-command structure for FAT commands . . . . . . . . . . . . . . . . XML sample of FAT commands with Windows Default as the value for the os-id attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of SSH dynamic target using the Base64 option . . . . . . . . . . . . . . . . . . . XML sample of a command using the Base64 option . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of continue-on-failure attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of disable-line-termination attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of ignore-response attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of is-special-character attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of a named connection used in conjunction with a dynamic target . . XML sample of a named connection in conjunction with a target name reference . XML sample of a request that uses the proxy command features . . . . . . . . . . . . . . . . XML sample configuration for known hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of public key authentication optional elements . . . . . . . . . . . . . . . . . . . XML sample of <verify-os> element in an adapter configuration . . . . . . . . . . . . . . . . XML sample of the . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of the command-group feature in an adapter request . . . . . . . . . . . . . . XML sample of the env-variables feature in an adapter request . . . . . . . . . . . . . . . . . XML sample of the executable-directory feature in an adapter configuration . . . . . XML sample of the File adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML template of the File adapter request with read action . . . . . . . . . . . . . . . . . . . . . XML sample of the File adapter request with read action . . . . . . . . . . . . . . . . . . . . . . XML sample of the File adapter response with read actionXML file type . . . . . . . XML sample of the File adapter response with read action and no tokenization . . . XML sample of the File adapter response with read action and header-false . . . . . XML sample of the File adapter response with read action and header set to true . XML template of the File adapter request with write actionTEXT file . . . . . . . . . . XML template of the File adapter request with write actionXML file . . . . . . . . . . XML sample of the File adapter request with write actionTEXT file . . . . . . . . . . . XML sample of the File adapter request with write action XML file . . . . . . . . . . . . . XML sample of the File adapter response with write action . . . . . . . . . . . . . . . . . . . .
Figures

19 21 24 25 26 26 27 27 28 29 29 30 30 31 31 32 32 33 34 35 36 37 38 38 39 39 40 46 48 48 49 50 52 53 54 54 55 55 56
1

XML template of the File adapter request with append action . . . . . . . . . . . . . . . . . . 56 XML sample of the File adapter request with append action . . . . . . . . . . . . . . . . . . . . 57 XML sample of the File adapter response with append action . . . . . . . . . . . . . . . . . . 58 XML sample of the File adapter request with a delete action . . . . . . . . . . . . . . . . . . . . 58 XML sample of the File adapter response with a delete action . . . . . . . . . . . . . . . . . . 59 XML sample of the Command Line adapter configuration . . . . . . . . . . . . . . . . . . . . . 61 XML sample of the Command Line adapter with empty configuration . . . . . . . . . . . 61 XML template of the Command Line adapter requestUNIX sample . . . . . . . . . . . 62 XML sample of the Command Line adapter requestUNIX sample . . . . . . . . . . . . . 62 XML sample of the Command Line adapter requestWindows sample . . . . . . . . . 64 XML sample of the Command Line adapter response . . . . . . . . . . . . . . . . . . . . . . . . . 64 XML sample of the Command Line adapter response . . . . . . . . . . . . . . . . . . . . . . . . . 67 XML sample of the Command Line adapter request to set environment variables Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 XML sample of the Command Line adapter request to clear environment variables Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 XML sample of the Command Line adapter response explaining environment variablesWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 XML sample of the Command Line adapter request using multiple commands Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 XML sample of the Command Line adapter response using multiple commands Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 XML sample of the Session-based CLI adapter configurationWindows platform 75 XML sample of the Session-based CLI adapter configuration to set environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 XML sample of the Session-based CLI adapter configuration to clear environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 XML sample of the Session-based CLI configuration with character-set . . . . . . . . . . 76 XML sample of the Session-based CLI adapter configuration with promptUNIX platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 XML sample of the Session-based Command Line configuration with expectUNIX platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 XML sample of the Session-based CLI adapter requestWindows . . . . . . . . . . . . . . 77 XML sample of the Session-based CLI adapter request for Command Group Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 XML sample of the Session-based CLI adapter request with persistent connectivity Windows platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 XML sample of the Session-based CLI adapter response with persistent connectivityWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 XML sample of the Session-based CLI adapter requestUNIX . . . . . . . . . . . . . . . . . 80 XML sample of the Session-based CLI adapter request with persistent connectivity UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 XML sample of the Session-based CLI adapter response with persistent connectivityUNIX platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 XML sample of the Command Line adapter request for the run-as feature (Windows)simple commands format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 XML sample of the Command Line adapter response for the run-as feature (Windows)simple commands format (part 1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . 84

BMC Atrium Orchestrator Base Adapters User Guide

XML sample of the Command Line adapter response for the run-as feature (Windows)simple commands format (part 2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 85 XML sample of the Command Line adapter request for the run-as feature (Windows)command group format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 XML sample of the Command Line adapter response for the run-as feature (Windows)command group format (part 1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 85 XML sample of the Command Line adapter response for the run-as feature (Windows)command group format (part 2 of 2)) . . . . . . . . . . . . . . . . . . . . . . . . . 86 XML sample of the Command Line adapter request for the run-as feature (Windows)FAT command format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 XML sample of the Command Line adapter response for the run-as feature (Windows)FAT command format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)simple commands format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)simple commands format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)command group format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)command group format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)FAT command format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)FAT command format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)simple commands format . . . . . . . . . 93 XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)simple commands format . . . . . . . . . 94 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)command group format . . . . . . . . . . 95 XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)command group format . . . . . . . . . . 96 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)FAT command format . . . . . . . . . . . . 97 XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)FAT command format . . . . . . . . . . . . 98 XML template of the SSH adapter configurationpassword approach . . . . . . . . . 103 XML template of the SSH adapter configurationprivate-key-file approach . . . . 103 XML sample of the SSH adapter configuration with CharSet . . . . . . . . . . . . . . . . . . 103 XML template of the SSH adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 XML sample of the SSH adapter request with use-pseudo-terminal command . . . 109 XML sample of the SSH adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 XML sample of the SSH adapter request with CharSet . . . . . . . . . . . . . . . . . . . . . . . . 110 XML sample of the SSH adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 XML sample of the SSH adapter configuration with KBI . . . . . . . . . . . . . . . . . . . . . . 115 XML sample of the SSH KBI adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 XML sample of the SSH KBI adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 XML template of the Kerberized SSH adapter (Java client) configuration . . . . . . . 121 XML sample of the Kerberized SSH adapter request (Java client) . . . . . . . . . . . . . . 125

Figures

XML sample of the Kerberized SSH adapter response (Java client) . . . . . . . . . . . . . 127 XML template of the Kerberized SSH adapter configuration (local client) using <ktgtcache-file> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 XML sample of the Kerberized SSH adapter request (local client) . . . . . . . . . . . . . . 135 XML sample of the Kerberized SSH adapter response (local client) . . . . . . . . . . . . 137 XML template of the Telnet adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 XML sample of the Telnet adapter configuration with multiple configs . . . . . . . . . 141 XML sample of the Telnet adapter configuration with CharSet . . . . . . . . . . . . . . . . . 141 XML template of the Telnet adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 XML sample of the Telnet adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 XML sample of the Telnet adapter with CharSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 XML sample of the Telnet adapter request for multiple configurations . . . . . . . . . . 145 XML sample of the Telnet adapter request with multiple commands . . . . . . . . . . . 146 XML sample of the Telnet adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 XML sample of the Telnet adapter response with multiple commands . . . . . . . . . . 149 XML template of the SCP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 XML sample of the SCP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 XML template of the SCP adapter request with get action . . . . . . . . . . . . . . . . . . . . . 156 XML sample of the SCP adapter request with get action . . . . . . . . . . . . . . . . . . . . . . 157 XML sample of the SCP adapter response with get action . . . . . . . . . . . . . . . . . . . . . 158 XML template of the SCP adapter request with put action . . . . . . . . . . . . . . . . . . . . . 161 XML sample of the SCP adapter request with put action . . . . . . . . . . . . . . . . . . . . . . 162 XML sample of the SCP adapter response with put action . . . . . . . . . . . . . . . . . . . . . 163 XML template of the FTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 XML sample of the FTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 XML sample of the FTP adapter configuration with Charset element . . . . . . . . . . . 167 XML sample of the FTP adapter request with a dynamic target . . . . . . . . . . . . . . . . 168 XML sample of the FTP adapter response with a dynamic target . . . . . . . . . . . . . . . 169 XML template of the FTP adapter request with append command . . . . . . . . . . . . . 170 XML sample of the FTP adapter request with append command . . . . . . . . . . . . . . . 170 XML sample of the FTP adapter response with append command . . . . . . . . . . . . . . 172 XML template of the FTP adapter request with cd command . . . . . . . . . . . . . . . . . . 173 XML sample of the FTP adapter request with cd command . . . . . . . . . . . . . . . . . . . . 174 XML sample of the FTP adapter response with cd command . . . . . . . . . . . . . . . . . . 175 XML template of the FTP adapter request with cdup command . . . . . . . . . . . . . . . . 176 XML sample of the FTP adapter request with cdup command . . . . . . . . . . . . . . . . . 177 XML sample of the FTP adapter response with cdup command . . . . . . . . . . . . . . . . 178 XML template of the FTP adapter request with get command . . . . . . . . . . . . . . . . . . 180 XML sample of the FTP adapter request with get command . . . . . . . . . . . . . . . . . . . 180 XML sample of the FTP adapter response with get command . . . . . . . . . . . . . . . . . . 182 XML template of the FTP adapter request with ls command . . . . . . . . . . . . . . . . . . . 183 XML sample of the FTP adapter request with ls command . . . . . . . . . . . . . . . . . . . . 183 XML sample of the FTP adapter response with ls command . . . . . . . . . . . . . . . . . . . 186 XML template of the FTP adapter request with mkdir command . . . . . . . . . . . . . . . 187 XML sample of the FTP adapter request with mkdir command . . . . . . . . . . . . . . . . 188 XML sample of the FTP adapter response with mkdir command . . . . . . . . . . . . . . . 189 XML template of the FTP adapter request with mode command . . . . . . . . . . . . . . . 190 XML sample of the FTP adapter request with mode command . . . . . . . . . . . . . . . . . 191 XML sample of the FTP adapter response with mode command . . . . . . . . . . . . . . . 192

BMC Atrium Orchestrator Base Adapters User Guide

XML template of the FTP adapter request with put command . . . . . . . . . . . . . . . . . XML sample of the FTP adapter request with put command . . . . . . . . . . . . . . . . . . XML sample of the FTP adapter response with put command . . . . . . . . . . . . . . . . . XML template of the FTP adapter request with pwd command . . . . . . . . . . . . . . . . XML sample of the FTP adapter request with pwd command . . . . . . . . . . . . . . . . . XML template of the FTP adapter response with pwd command . . . . . . . . . . . . . . . XML template of the FTP adapter request with rename command . . . . . . . . . . . . . XML sample of the FTP adapter request with rename command . . . . . . . . . . . . . . . XML sample of the FTP adapter response with rename command . . . . . . . . . . . . . XML template of the FTP adapter request with rm command . . . . . . . . . . . . . . . . . XML sample of the FTP adapter request with rm command . . . . . . . . . . . . . . . . . . . XML sample of the FTP adapter response with rm command . . . . . . . . . . . . . . . . . XML template of the FTP adapter request with the rmdir command . . . . . . . . . . . . XML sample of the FTP adapter request with rmdir command . . . . . . . . . . . . . . . . XML sample of the FTP adapter response with rmdir command . . . . . . . . . . . . . . . XML template of the FTP adapter request with stat command . . . . . . . . . . . . . . . . . XML sample of the FTP adapter request with stat command . . . . . . . . . . . . . . . . . . XML sample of the FTP adapter response with stat command . . . . . . . . . . . . . . . . . XML sample of the FTP adapter request with multiple commands . . . . . . . . . . . . . XML sample of the FTP adapter response with multiple commands (part 1 of 3) . XML sample of the FTP adapter response with multiple commands (part 2 of 3) . XML sample of the FTP adapter response with multiple commands (part 3 of 3) . XML template of the SFTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML template of the SFTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML template of the SFTP adapter request with cd command . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter request with cd command . . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter response with cd command . . . . . . . . . . . . . . . . . XML template of the SFTP adapter request with chgrp command . . . . . . . . . . . . . . XML sample of the SFTP adapter request with chgrp command . . . . . . . . . . . . . . . XML sample of the SFTP adapter response with chgrp command . . . . . . . . . . . . . . XML template of the SFTP adapter request with chmod command . . . . . . . . . . . . . XML sample of the SFTP adapter request with chmod command . . . . . . . . . . . . . . XML sample of the SFTP adapter response with chmod command . . . . . . . . . . . . . XML template of the SFTP adapter request with chown command . . . . . . . . . . . . . XML sample of the SFTP adapter request with chown command . . . . . . . . . . . . . . XML sample of the SFTP adapter response with chown command . . . . . . . . . . . . . XML template of the SFTP adapter request with get command . . . . . . . . . . . . . . . . XML sample of the SFTP adapter request with get command . . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter response with get command . . . . . . . . . . . . . . . . XML sample of the SFTP adapter request with get-dir command . . . . . . . . . . . . . . XML sample of the SFTP adapter request with get-dir command . . . . . . . . . . . . . . XML sample of the SFTP adapter response with get-dir command . . . . . . . . . . . . . XML template for a SFTP adapter request with lcd command . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter request with lcd command . . . . . . . . . . . . . . . . . . XML sample of the SFTP adapter response with lcd command . . . . . . . . . . . . . . . . XML template of the SFTP adapter request with lpwd command . . . . . . . . . . . . . . XML sample of the SFTP adapter request with lpwd command . . . . . . . . . . . . . . . . XML sample of the SFTP adapter response with the lpwd command . . . . . . . . . . .

194 194 196 197 197 199 200 201 202 203 204 205 206 207 209 210 210 212 213 214 215 216 220 220 220 224 224 226 229 229 231 234 234 235 239 239 241 244 244 246 249 249 251 254 254 256 259 259 261

Figures

XML template of the SFTP adapter request with ls command . . . . . . . . . . . . . . . . . . 264 XML sample of the SFTP adapter request with ls command . . . . . . . . . . . . . . . . . . . 264 XML template of the SFTP adapter request with ls command . . . . . . . . . . . . . . . . . . 267 XML template of the SFTP adapter request with mkdir command . . . . . . . . . . . . . . 270 XML sample of the SFTP adapter request with mkdir command . . . . . . . . . . . . . . . 270 XML sample of the SFTP adapter response with mkdir command . . . . . . . . . . . . . . 272 XML template of the SFTP adapter request with mkdirs command . . . . . . . . . . . . . 275 XML sample of the SFTP adapter response with mkdirs command . . . . . . . . . . . . . 277 XML template of the SFTP adapter request with put command . . . . . . . . . . . . . . . . 280 XML sample of the SFTP adapter request with put command . . . . . . . . . . . . . . . . . . 280 XML sample of the SFTP adapter response with put command . . . . . . . . . . . . . . . . 282 XML template of the SFTP adapter request with put-dir command . . . . . . . . . . . . 285 XML sample of the SFTP adapter request with put-dir command . . . . . . . . . . . . . . 285 XML sample of the SFTP adapter response with put-dir command . . . . . . . . . . . . 287 XML template of the SFTP adapter request with pwd command . . . . . . . . . . . . . . . 290 XML sample of the SFTP adapter request with pwd command . . . . . . . . . . . . . . . . 290 XML sample of the SFTP adapter response with pwd command . . . . . . . . . . . . . . . 292 XML template of the SFTP adapter request with rename command . . . . . . . . . . . . 295 XML sample of the SFTP adapter request with rename command . . . . . . . . . . . . . 295 XML sample of the SFTP adapter response with rename command . . . . . . . . . . . . 297 XML template for a SFTP adapter request with rm command . . . . . . . . . . . . . . . . . 300 XML sample of the SFTP adapter request with rm command . . . . . . . . . . . . . . . . . . 300 XML sample of the SFTP adapter response with rm command . . . . . . . . . . . . . . . . . 302 XML template of the SFTP adapter request with symlink command . . . . . . . . . . . . 305 XML sample of the SFTP adapter request with symlink command . . . . . . . . . . . . . 305 XML sample of the SFTP adapter response with symlink command . . . . . . . . . . . . 307 XML sample of the SFTP adapter request with multiple commands . . . . . . . . . . . . 307 XML sample of the SFTP adapter response with multiple commands (part 1 of 3) 309 XML sample of the SFTP adapter response with multiple commands (part 2 of 3) 310 XML sample of the SFTP adapter response with multiple commands (part 3 of 3) 311 XML template of the Windows command adapter configuration . . . . . . . . . . . . . . . 316 XML sample of the Windows command adapter configuration using the xCmd utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 XML sample of the Windows command adapter configuration using SSH . . . . . . . 317 XML template of the Windows Command adapter request . . . . . . . . . . . . . . . . . . . . 319 XML sample of the Windows Command adapter request . . . . . . . . . . . . . . . . . . . . . 319 XML sample of the Windows Command with systeminfo command . . . . . . . . . . . 320 XML sample of the Windows Command adapter request with a relative path . . . 320 XML sample of the Windows Command adapter request with a full path . . . . . . . 320 XML sample of the Windows Command adapter request with script execution . . 321 XML sample of the Windows Command adapter response using the xCmd utility . . 323 XML Sample of the Windows Command adapter response using SSH . . . . . . . . . . 324 XML sample of the Windows Command adapter response with script execution . 325 XML template of the PowerShell adapter configuration . . . . . . . . . . . . . . . . . . . . . . . 327 XML sample of the PowerShell adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . 329 XML sample of the PowerShell adapter configuration with <powershell-consolefile> tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 XML template of the PowerShell adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

BMC Atrium Orchestrator Base Adapters User Guide

XML sample of the PowerShell adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 XML sample of the PowerShell adapter request with get-service command . . . . . 332 XML sample of the PowerShell adapter request with relative path . . . . . . . . . . . . . 333 XML sample of the PowerShell adapter request with full path . . . . . . . . . . . . . . . . . 333 XML sample of the PowerShell adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 XML template of the HTTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 XML sample of the HTTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 XML template of the HTTP adapter request with a get action . . . . . . . . . . . . . . . . . 340 XML sample of the HTTP adapter request with a get action . . . . . . . . . . . . . . . . . . . 340 XML sample of the HTTP adapter request with NTLM authentication . . . . . . . . . . 341 XML sample of the HTTP adapter response to a request with get action when <dataformat> is HTML for any <Content-Type> . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 XML sample of the HTTP adapter response to an HTTP adapter request with a get action when <data-format> is XHTML or XML and <Content-Type> of HTTP response is well-formed text, HTML, or XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 HTTP adapter response elements to a request with a get action when <data-format> is XHTML or XML and <Content-Type> of the HTTP response is not well-formed TEXT, HTML, or XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 HTTP adapter request with a post actionsingle element format . . . . . . . . . . . . . . 346 HTTP adapter request with a post actionparent and child format . . . . . . . . . . . . 346 HTTP adapter request with post actionentry, key-value format . . . . . . . . . . . . . . 347 XML sample of the HTTP adapter request with post actionentry, key, and value pair tags format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 XML sample of the HTTP adapter response with post actionsimple text data format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 XML sample of the HTTP adapter response with post actionparent and child format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 XML sample of the HTTP adapter response with post actionentry, key, and value pair tags format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 XML sample of the HTTP adapter request with put action . . . . . . . . . . . . . . . . . . . . 353 XML sample of <connection-properties> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 XML sample of simple text format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 XML sample of parent and child format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 XML sample of entry, key, value pairs format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 XML sample of the HTTP adapter response with put action . . . . . . . . . . . . . . . . . . . 354 XML sample of the HTTP adapter request with a delete action . . . . . . . . . . . . . . . . 355 XML sample of the HTTP adapter response with a delete action . . . . . . . . . . . . . . . 356 XML sample of the HTTP adapter request with header fields . . . . . . . . . . . . . . . . . . 357 XML sample of the JMS actor adapter for the IBM WebSphere MQ server . . . . . . . 360 XML sample of the JMS monitor adapter for the IBM WebSphere MQ server . . . . 361 XML sample of the JMS request for the IBM WebSphere MQ serverExample 1 . 361 XML sample of the JMS request for the IBM WebSphere MQ serverExample 2 . 362 XML template of the JMS actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . 364 XML sample of the JMS actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . 364 XML sample for the JMS adapter configuration with a TIBCO EMS . . . . . . . . . . . . 365 XML template of the JMS actor adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 XML sample of the synchronous JMS actor adapter request . . . . . . . . . . . . . . . . . . . 369 XML sample of the asynchronous JMS actor adapter request . . . . . . . . . . . . . . . . . . 370 XML template of the JMS actor adapter asynchronous response . . . . . . . . . . . . . . . 371

Figures

XML sample of the JMS synchronous actor adapter response . . . . . . . . . . . . . . . . . . 372 XML template of the JMS monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . 376 XML sample of the JMS monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . 377 XML sample of the JMS monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 XML sample of the JMS monitor adapter event message responseByte content only 379 XML sample of the JMS monitor adapter event message responsemixed content . . 380 XML template of the Script adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 XML sample of the Script adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 XML template of the Script adapter request with the <script> element . . . . . . . . . . 383 XML template of the Script adapter request with the <script-path> element . . . . . . 384 XML sample of the Script adapter request with the <script> element as Jython . . . 384 XML sample of the Script adapter request with the <script> element as Perl . . . . . 384 XML sample of the Script adapter request with <script-path> element . . . . . . . . . . 385 XML sample of the Script adapter response with the script element as Jython . . . . 385 XML sample of the Script adapter response with the script element as Perl . . . . . . 385 XML template of the SNMP actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . 386 XML template of the SNMP adapter request with get action . . . . . . . . . . . . . . . . . . . 388 XML sample of the SNMP adapter request with get action . . . . . . . . . . . . . . . . . . . . 388 XML sample of the SNMP adapter response with get action . . . . . . . . . . . . . . . . . . . 389 XML template of the SNMP adapter request with notification action for SNMPv1 trap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 XML sample of the SNMP actor adapter request with notification action for SNMPv1 trap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 XML template of the SNMP adapter request with notification action for SNMPv2c trap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 XML sample of the SNMP adapter request with notification action for SNMPv2c trap 393 XML sample response of the SNMP adapter with notification action . . . . . . . . . . . 394 XML template of the SNMP monitor adapter configuration . . . . . . . . . . . . . . . . . . . 395 XML sample of the SNMP monitor adapter event with <mibs-directory> element defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 XML sample of the SNMP monitor adapter event without the <mibs-directory> element defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 XML sample of method one for defining a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 XML sample of method two for defining a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 XML sample of the SQL actor adapter configuration without a URL . . . . . . . . . . . . 403 XML sample of the SQL actor adapter configuration with a URL . . . . . . . . . . . . . . . 404 XML sample of an SQL actor adapter configuration for Sybase Kerberos Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 XML sample of an SQL actor adapter with an empty configuration . . . . . . . . . . . . . 404 XML sample of the SQL standard actor adapter request (legacy) . . . . . . . . . . . . . . . 405 XML sample of the SQL standard actor adapter request (dynamic) . . . . . . . . . . . . . 406 XML sample of the SQL standard actor adapter request with Sybase Kerberos Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 XML sample of the SQL standard actor adapter response (legacy) . . . . . . . . . . . . . . 407 XML sample of the SQL standard actor adapter response (dynamic) . . . . . . . . . . . . 409

BMC Atrium Orchestrator Base Adapters User Guide

XML sample of the SQL standard actor adapter response with Sybase Kerberos Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 XML sample of the SQL actor adapter request with a parameterized statement (legacy) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 XML sample of the SQL actor adapter request with a parameterized statement (dynamic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 XML sample of the SQL actor adapter request with a stored procedure . . . . . . . . . 415 XML sample of the SQL actor adapter response with a parameterized statement (legacy) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 XML sample of an SQLparameterized statement actor adapter response (dynamic) 418 XML sample of the SQL actor adapter request supporting Oracle XMLType data type 420 XML sample of the SQL actor adapter response supporting Oracle XMLType data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 XML sample of method 1 for defining a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 XML sample of method 2 for defining a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 XML sample of the SQL monitor adapter configurationnon-URL . . . . . . . . . . . . 429 XML sample of the SQL monitor adapter configurationnon-URL supporting a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 XML sample of the SQL monitor adapter configuration with a function returning an integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 XML sample of the SQL monitor adapter configurationURL . . . . . . . . . . . . . . . . 432 XML sample of the SQL monitor adapter configuration with Sybase Kerberos Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 XML sample of the SQL monitor adapter event when the <single-monitor-event> element is true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 XML sample of the SQL monitor adapter event supporting a stored procedure . . 434 XML sample of the SQL monitor adapter when the <single-monitor-event> element is falsesingle event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 XML sample of the SQL monitor adapter when the <single-monitor-event> element is falsetwo events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 XML template of the Web Services adapter configuration . . . . . . . . . . . . . . . . . . . . . 442 XML sample of the Web Services adapter configuration that does not clear the cache 443 XML sample for the Web Services adapter configuration with proxy settings . . . . 443 XML sample of the Web Services adapter configuration for key-files mode . . . . . . . 443 XML sample of the Web Services adapter configuration for key-data mode . . . . . . 444 XML sample of the Web Services adapter configuration for key-store mode . . . . . . 444 XML sample of the Web Services actor adapter requestmethod one . . . . . . . . . . 448 XML sample of the Web Services actor adapter request with HTTPS Client Authenticationmethod one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 XML sample of the Web Services actor adapter request with NTLM Authentication with HTTP support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 XML sample of the Web Services actor adapter request with NTLM Authentication with HTTPS support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 XML sample of the Web Services adapter responsemethod one . . . . . . . . . . . . . . 450 XML sample of the Web Services adapter response with Client Authentication method one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Figures

XML sample of the Web Services adapter response with NTLM authentication with HTTP support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 XML sample of the Web Services adapter response with NTLM authentication with HTTPS support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 XML template of the Web Services adapter requestmethod two . . . . . . . . . . . . . . 454 XML sample of the Web Services adapter requestmethod two . . . . . . . . . . . . . . . 454 XML sample of the Web Services adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 XML sample of the Web Services adapter requestMake SOAP RequestPayload mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 XML sample of the Web Services adapter response to a request for Make SOAP RequestPayload mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 XML sample of the Web Services adapter request for Make SOAP Request in Message mode and using username-token and X.509 digital signature authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 XML sample of the Web Services adapter request for Make SOAP Request in Message mode and using timestamp and X.509 digital signature authentication . . 463 XML sample of the Web Services adapter request for Make SOAP Request in Message mode with HTTPS client authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 464 XML sample of the Web Services adapter responseMake SOAP Request in Message mode and using username token and X.509 digital signature authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 XML sample of the Web Services adapter response to a request for Make SOAP Request in Message mode and using timestamp and X.509 digital signature authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 XML sample of the Web Services adapter response to a request for Make SOAP Request in Message mode with HTTP client authentication . . . . . . . . . . . . . . . . . 467 XML sample of the Web Services adapter requestPoll Asynchronous Response 468 XML sample of the Web Services adapter response with Poll Asynchronous Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 XML template of the SMTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 XML sample of the SMTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 XML sample of the SMTP adapter configuration with <max-attachment-size> . . . 476 XML template of the SMTP adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 XML sample of the SMTP adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 XML sample of the SMTP adapter request with attachment support . . . . . . . . . . . . 478 XML sample of the SMTP adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 XML template of the IMAP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 XML sample of the IMAP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 XML sample of the IMAP adapter configuration with attachment download settings 486 XML sample of the IMAP adapter configuration with additional settings . . . . . . . 486 XML sample of the IMAP adapter event with an attachment successfully downloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 XML sample of the IMAP mail adapter event with an attachment that cannot be downloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 XML template of the POP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 XML sample of the POP mail adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 496 XML sample of the POP mail adapter configuration with additional settings . . . . 497

10

BMC Atrium Orchestrator Base Adapters User Guide

XML sample of the POP mail adapter configuration with attachment download settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 XML sample of the POP adapter event with attachments that are successfully downloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 XML sample of the POP adapter event with attachments that cannot be downloaded 500 XML sample of the PowerShell adapter request for the get-service command . . . . 517 XML sample of the Terminal Kerberos SSH1 adapter configuration with ktgt-cachefile-name parameter and a valid TGT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 XML sample of the Terminal Kerberos SSH1 configuration with dynamic targets 610 Kerberos SSH2 configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 XML sample of the Terminal Kerberos SSH2 adapter configuration with krb-realm . 614 XML sample of the Terminal Kerberos SSH2 adapter configuration with dynamic targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 XML sample of the Terminal Kerberos SSH2 adapter configuration with dynamic targets using user name and password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616

Figures

11

12

BMC Atrium Orchestrator Base Adapters User Guide

Tables
Call Adapter activity propertiesstatic value as the adapter input . . . . . . . . . . . . . . 18 Actor adapter request elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Monitor adapter event elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 <Command> attributes for directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Optional elements for verifying the encryption key . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Optional elements for public key authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Terminal adapter feature overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Adapter request elements for the File adapter with read action . . . . . . . . . . . . . . . . . 47 Sample delimiter formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Elements of a File adapter response to a request with read actionXML file type 49 Elements of a File adapter response to a request with read action and no tokenization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Elements of a File adapter response to a request with read action and tokenization header-false . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Elements of a File adapter response to a request with read action and tokenization header-true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Adapter request elements for the File adapter with write action . . . . . . . . . . . . . . . . 54 Elements of a File adapter response to a request with write action . . . . . . . . . . . . . . 55 Adapter request elements for the File adapter with append action . . . . . . . . . . . . . . 56 Elements of a File adapter response to a request with append action . . . . . . . . . . . . 57 Adapter request element for the File adapter with a delete action . . . . . . . . . . . . . . 58 Elements of a File adapter response to a request with a delete action . . . . . . . . . . . . 59 Configuration node elements of the Command Line adapter . . . . . . . . . . . . . . . . . . . 61 Adapter request elements for the Command Line adapter . . . . . . . . . . . . . . . . . . . . . 63 Elements of a Command Line adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Configuration node elements of the Windows Session-based CLI adapter . . . . . . . . 74 Adapter request attributes for the run-as feature in the Command Line adapter Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Adapter request attributes for the run-as feature in the Command Line adapter Linux or UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Adapter request attributes for the run-as with Kerberos authentication feature in the Command Line adapterLinux or UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Configuration node elements of the SSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Adapter request elementsSSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Elements of an SSH adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Configuration node elementsKerberized SSH adapter . . . . . . . . . . . . . . . . . . . . . . 119 Adapter request elements of the Kerberized SSH adapter Java client . . . . . . . . . . . 122 Elements of a of a Kerberized SSH adapter response to a request with a Java client . 125 Configuration node elements for the Kerberized SSH adapter with local client . . 129
Tables 1

Adapter request elements of the Kerberized SSH adapter (local client) . . . . . . . . . 132 Elements of a Kerberized SSH adapter response (local client) . . . . . . . . . . . . . . . . . 135 Configuration node elementsTelnet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Adapter request elements for the Telnet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Elements of a Telnet adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Configuration node elementsSCP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Adapter request elementsSCP adapter with get action . . . . . . . . . . . . . . . . . . . . . 154 Elements of an SCP adapter response to a request with get action . . . . . . . . . . . . . 157 Adapter request elements for the SCP adapter with put action . . . . . . . . . . . . . . . . 159 Elements of an SCP adapter response to a request with put action . . . . . . . . . . . . . 162 FTP adapter configuration elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 FTP adapter commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Adapter request elements of the FTP adapter with append command . . . . . . . . . 169 Elements of an FTP adapter response to a request with append command . . . . . . . 171 Adapter request elements of the FTP adapter with cd Command . . . . . . . . . . . . . . . 173 Elements of an FTP adapter response to a request with cd command . . . . . . . . . . . 174 Adapter request elementsFTP adapter with cdup command . . . . . . . . . . . . . . . . 176 Elements of an FTP adapter response to a request with cdup command . . . . . . . . . 177 Adapter request elements for the FTP adapter with get command . . . . . . . . . . . . . 179 Elements of an FTP adapter response to a request with get command . . . . . . . . . . 180 Adapter request elementsFTP adapter with ls command . . . . . . . . . . . . . . . . . . . 182 Elements of an FTP adapter response to a request with ls command . . . . . . . . . . . 184 Adapter request elements of the FTP adapter with mkdir command . . . . . . . . . . . 187 Elements of an FTP adapter response to a request with mkdir command . . . . . . . 188 Adapter request elements of the FTP adapter with mode command . . . . . . . . . . . . 190 Elements of an FTP adapter response to a request with mode command . . . . . . . . 191 Adapter request elements of the FTP adapter with put Command . . . . . . . . . . . . . . 193 Elements of an FTP adapter response to a request with put command . . . . . . . . . . 194 Adapter request elements of the FTP adapter with pwd command . . . . . . . . . . . . . 196 Elements of an FTP adapter response to a request with pwd command . . . . . . . . . 198 Adapter request elementsFTP adapter with rename command . . . . . . . . . . . . . . 200 Elements of an FTP adapter response to a request with rename command . . . . . . 201 Adapter request elements of the FTP adapter with rm command . . . . . . . . . . . . . . . 203 Elements of an FTP adapter response to a request with rm command . . . . . . . . . . 204 Adapter request elements of the FTP adapter with rmdir command . . . . . . . . . . . . 206 Elements of an FTP adapter response to a request with rmdir command . . . . . . . . 207 Adapter request elements of the FTP adapter with stat command . . . . . . . . . . . . . . 209 Elements of an FTP adapter response to a request with stat command . . . . . . . . . . 211 Configuration node elementsSFTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SFTP adapter commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Adapter request elementsSFTP adapter with cd command . . . . . . . . . . . . . . . . . . 222 Elements of an SFTP adapter response to a request with cd command . . . . . . . . . . 225 Adapter request elements for the SFTP adapter with chgrp command . . . . . . . . . . 227 Elements of an SFTP adapter response to a request with chgrp command . . . . . . . 230 Adapter request elements of the SFTP adapter with chmod command . . . . . . . . . 232 Elements of an SFTP adapter response to a request with chmod command . . . . . . 235 Adapter request elements of the SFTP adapter with chown command . . . . . . . . . . 237 Elements of an SFTP adapter response to a request with chown command . . . . . . 240 Adapter request elements of the SFTP adapter with get command . . . . . . . . . . . . . 242

BMC Atrium Orchestrator Base Adapters User Guide

Elements of an SFTP adapter response to a request with get command . . . . . . . . . 245 Adapter request elements of the SFTP adapter with get-dir command . . . . . . . . . . 247 Elements of an SFTP adapter response to a request with get-dir command . . . . . . 250 Adapter request elements of the SFTP adapter with lcd command . . . . . . . . . . . . . 252 Elements of an SFTP adapter response to a request with Icd command . . . . . . . . . 255 Adapter request elements of the SFTP adapter with Ipwd command . . . . . . . . . . . 257 Elements of an SFTP adapter response to a request with lpwd command . . . . . . . 260 Adapter request elements of the SFTP adapter with ls command . . . . . . . . . . . . . . 262 Elements of an SFTP adapter response to a request with Is command . . . . . . . . . . 265 Adapter request elements of the SFTP adapter with mkdir command . . . . . . . . . . 268 Elements of an SFTP adapter response to a request with mkdir command . . . . . . 271 Adapter request elements of the SFTP adapter with mkdirs command . . . . . . . . . . 273 Elements of an SFTP adapter response to a request with mkdirs command . . . . . . 275 Adapter request elements of the SFTP adapter with put command . . . . . . . . . . . . 278 Elements of an SFTP adapter response to a request with put command . . . . . . . . 281 Adapter request elements of the SFTP adapter with put-dir command . . . . . . . . . 283 Elements of an SFTP adapter response to a request with put-dir command . . . . . . 286 Adapter request elements for the SFTP adapter with pwd command . . . . . . . . . . 288 Elements of an SFTP adapter response to a request with pwd command . . . . . . . 291 Adapter request elements of the SFTP adapter with rename command . . . . . . . . . 293 Elements of an SFTP adapter response to a request with rename command . . . . . 296 Adapter request elements for the SFTP adapter with rm command . . . . . . . . . . . . 298 Elements of an SFTP adapter response to a request with rm command . . . . . . . . . 301 Adapter request elements of the SFTP adapter with symlink command . . . . . . . . 303 Elements of an SFTP adapter response to a request with symlink command . . . . . 306 Adapter configuration elements for the Windows Command adapter . . . . . . . . . . 314 Adapter request elements of the Windows Command adapter . . . . . . . . . . . . . . . . 318 Elements of a Windows Command adapter response . . . . . . . . . . . . . . . . . . . . . . . . 321 PowerShell adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Adapter request elements for the PowerShell adapter . . . . . . . . . . . . . . . . . . . . . . . . 331 Configuration elements for the HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Elements for an HTTP adapter request with a get action . . . . . . . . . . . . . . . . . . . . . . 339 Elements of an HTTP adapter response to a request with get action when <dataformat> is HTML for any <Content-Type> of HTTP response . . . . . . . . . . . . . . . 341 Elements of an HTTP adapter response to a request with a get action when <dataformat> is XHTML or XML and <Content-Type> is well-formed text, HTML, or XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Adapter request elements for HTTP adapter with post action . . . . . . . . . . . . . . . . . 345 Elements of an HTTP request with a post actionentry, key-value pair tags format . 347 Elements of an HTTP adapter response to a request with post actionentry, keyvalue pair tags format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Adapter request elements for the HTTP adapter with put action . . . . . . . . . . . . . . . 352 Adapter request elements for the HTTP adapter with a delete action . . . . . . . . . . . 354 HTTP actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 JMS actor adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Actor adapter request elements for JMS adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 JMS actor adapter response elements (asynchronous) . . . . . . . . . . . . . . . . . . . . . . . . 370 JMS actor adapter response elements (synchronous) . . . . . . . . . . . . . . . . . . . . . . . . . 371

Tables

JMS monitor adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 JMS monitor adapter event elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Configuration node elements of the Script adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 Adapter request elements for Script adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Script adapter response elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Adapter request elements for SNMP adapter with get action . . . . . . . . . . . . . . . . . . 387 Elements of an SNMP actor adapter response to a request with get action . . . . . . . 389 SNMP actor adapter request with notification action v1 SNMP trap elements . . . . 390 Adapter request elements for the SNMP adapter with notification action for SNMPv2c trap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Elements of an SNMP actor adapter response to a request with notification action . . . 394 SNMP monitor adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . 395 SNMP monitor adapter event elements with the <mibs-directory> element defined . 396 SNMP monitor adapter without <mib-directory> definition elements . . . . . . . . . . 397 SQL actor adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Adapter request elements for SQL standard actor adapter . . . . . . . . . . . . . . . . . . . . . 406 SQL standard actor adapter response elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 SQL standard actor adapter response elements (dynamic) . . . . . . . . . . . . . . . . . . . . . 408 SQL parameterized statement actor adapter request elements . . . . . . . . . . . . . . . . . 412 SQLparameterized statement actor adapter response elements . . . . . . . . . . . . . . 416 Third party (client-specific) JAR files to be copied . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Oracle client-side files required to deploy a JDBC OCI application . . . . . . . . . . . . . 424 SQL monitor adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 SQL monitor with single monitor event true adapter event elements . . . . . . . . . . . 433 SQL single monitor adapter event false- event two elements . . . . . . . . . . . . . . . . . . . 435 Web Services adapter configuration elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Web Services adapter request elementsmethod one . . . . . . . . . . . . . . . . . . . . . . . . 447 Web Services adapter requestmethod two elements . . . . . . . . . . . . . . . . . . . . . . . . 452 Web Services adapter request JAX-WS methodPayload mode elements . . . . . . . 456 Elements in the Web Services adapter request for Make SOAP request with JAX-WS method in Message mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 Element for Web Services adapter request with Poll Asynchronous Response . . . . 467 Differences between method one, method two, and JAX-WS approach . . . . . . . . . . 469 Configuration node elementsSMTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 Adapter request elements SMTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Adapter response elementsSMTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 IMAP mail adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 IMAP mail adapter event with <attachments> element . . . . . . . . . . . . . . . . . . . . . . . . 486 IMAP mail adapter event with an attachment having elements that cannot be downloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 POP mail adapter configuration node elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 POP mail with attachments successfully downloaded adapter elements . . . . . . . . . 497 POP mail adapter event with attachments that cannot be downloaded elements . 499 Process inputsTokenize String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Process outputsTokenize String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Process inputssend email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Process inputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

BMC Atrium Orchestrator Base Adapters User Guide

Process outputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsPost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsPost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputssend body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsSend Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsSend Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsSend Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter request elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsAd Hoc Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsAd Hoc Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsAd Hoc Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsAd Hoc Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample delimiter formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputscd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputs -cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputs -cdup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputscdup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsmkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsmkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process inputsmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process outputsmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

507 508 509 510 511 512 513 514 515 515 516 517 518 518 519 520 521 522 523 524 525 527 529 531 532 534 535 536 536 536 537 537 538 538 539 540 541 542 543 543 544 545 546 547 548 549 550 551 552

Tables

Process inputsput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 Process outputsput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 Process inputspwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 Process outputspwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Process inputsrename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Process outputsrename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 Process inputsrm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 Process outputsrm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Process inputsrmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Process outputsrmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Process inputsstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 Process outputsstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Process inputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Process outputsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Process inputsPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Process outputsPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 Process inputscd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 Process outputscd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 Process inputschgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Process outputschgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 Process inputschmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Process outputschmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Process inputschown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Process outputschown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 Process inputsget-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 Process outputsget-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 Process inputsget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 Process outputsget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Process inputsIcd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Process outputsIcd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Process inputslpwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Process outputslpwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Process inputsls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Process outputsls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Process inputsmkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Process outputsmkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Process inputsmkdirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Process outputsmkdirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Process inputsput dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Process outputsput dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 Process inputsput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 Process outputsput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 Process inputspwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Process outputs -pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 Process inputsrename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 Process outputsrename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 Process inputsrm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 Process outputsrm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601

BMC Atrium Orchestrator Base Adapters User Guide

Process inputssymlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Process outputssymlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Process inputsCommand Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Process outputsCommand line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 Process outputsCommand line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 Process inputsTerminal SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Process outputsTerminal SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Terminal Kerberos SSH1 adapter configuration elements with ktgt-cache-file-name parameter and a valid TGT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Terminal Kerberos SSH1 adapter configuration elements with dynamic targets . . 610 Terminal Kerberos SSH2 configuration elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 Terminal Kerberos SSH2 configuration elements with dynamic targets . . . . . . . . . 617 Process inputsTelnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Process outputsTelnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Process inputsWindows command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Process outputsWindows command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Process inputsMake SOAP requestmethod one . . . . . . . . . . . . . . . . . . . . . . . . . . 623 Process outputsMake SOAP requestmethod one . . . . . . . . . . . . . . . . . . . . . . . . . 624 Process inputsMake SOAP requestmethod two . . . . . . . . . . . . . . . . . . . . . . . . . . 624 Process outputsMake SOAP request method two . . . . . . . . . . . . . . . . . . . . . . . . . . 625

Tables

BMC Atrium Orchestrator Base Adapters User Guide

About this book

To request printed books or to view online books and notices (such as release notes and technical bulletins), see the Customer Support website at http://www.bmc.com/support_home. Some product shipments also include the online books on a documentation CD.

NOTE
Online books are formatted as PDF or HTML files. To view, print, or copy PDF books, use the free Adobe Reader from Adobe Systems. If your product installation does not install the reader, you can obtain the reader at http://www.adobe.com.

The software also offers online Help. To access Help, press F1 within any product or click the Help button in graphical user interfaces (GUIs).

Related publications
The following related publications supplement this book and the online Help:
Document BMC Atrium Orchestrator System Administration Guide BMC Atrium Orchestrator Development Studio User Guide BMC Atrium Orchestrator Common Actions User Guide BMC Atrium Orchestrator Installation Guide BMC Atrium Orchestrator Security Guide Description Provides conceptual and procedural information about managing the BMC Atrium Orchestrator grid environment Describes how to use BMC Atrium Orchestrator Development Studio Contains conceptual information as well as inputs and outputs for the operations actions management module workflows Describes how to plan for, install, and upgrade the BMC Atrium Orchestrator product Describes how to use BMC Atrium Orchestrator Access Manager to manage accounts and single sign-on configurations

BMC Atrium Orchestrator User Guide for Base Contains details about configuring and using the BMC Atrium Adapters Orchestrator base adapters BMC Atrium Orchestrator User Guides for Contain details about configuring and using the BMC Atrium Application Adapters Orchestrator application adapters

About this book

Conventions

Conventions
This book uses the following special conventions:
s

All syntax, operating system terms, and literal examples are presented in this typeface. Variable text in path names, system messages, or syntax is displayed in italic text:
testsys/instance/fileName

The symbol => connects items in a menu sequence. For example, Actions => Create Test instructs you to select the Create Test command from the Actions menu.

Searching across PDF documents in a folder and its subfolders

With Adobe Reader version 7.0 and later, you can perform a full-text search across all PDFs that reside in the same folder and its subfolders. If you do not have Adobe Reader version 7.0 or later, you can download the latest Adobe Reader version from http://www.adobe.com for free.

To search for a word or phrase in PDF documents in a single directory 1 Start Adobe Reader. 2 In the toolbar, click the search icon (binoculars).
If the search icon is missing, right-click the toolbar to find more toolbar options. Different versions of Adobe Reader put the option in different places.

3 In the Search window, select All PDF Documents in under Where would you like to
search?

4 Click the folder selection box and select Browse for Location. 5 Browse to the top-level folder that contains the PDF documents that you want to
search.

6 In the What word or phrase would you like to search for? box, type a search term and
click Search.

10

BMC Atrium Orchestrator Base Adapters User Guide

Searching across PDF documents in a folder and its subfolders

The search tool searches for the specified term in all of the PDFs in the chosen directory and its subdirectories and displays the results.

About this book

11

Searching across PDF documents in a folder and its subfolders

12

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

1
13 14 16 20 21

Overview of base adapters

This chapter presents the following topics: Adapter overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Actor adapter requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Actor adapter responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitor adapter events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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:

s

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.

Chapter 1 Overview of base adapters

13

Configuring the adapter

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

Configuring the adapter

Adapters are configured in Grid Manager, using an XML document to define the connection details and adapter properties. For each adapter, this guide includes the adapter type, a table outlining the adapter configuration fields, and an XML template for a configuration node, which is an XML file that contains the adapter configuration properties. Each adapter requires specific information in the configuration node to enable communications between systems or applications and processes. While each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties.

14

BMC Atrium Orchestrator Base Adapters User Guide

Configuring the adapter

The form view provides an easy-to-use interface for configuring adapters. It 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.

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 check box corresponding for the type of
adapter to be added. The adapter type use the following naming convention: ro-adapter-adapter type. For example, the adapter type for the IMAP adapter would be ro-adapterimap.

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 on page 16 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. This step is not required for base adapters that can be fully configured using the form.

Chapter 1 Overview of base adapters

15

Actor adapter requests

1. On the Warning message that appears, click Switch View. 2. In the Properties text box, use XML format to enter the configuration elements and attributes not available as fields in the form view. 3. Click OK.

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 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 BMC Atrium Orchestrator Development Studio User Guide contains the detailed steps to establish adapter configurations on the grid and assign them to individual peers. In Grid Manager, you can create multiple adapters with the same type to accommodate different configuration node properties, provided that you give the adapters unique names.

Actor adapter requests

Actor adapters use requests to obtain data from external systems and, in some cases, affect data in those systems. These requests are configured in BMC Atrium Orchestrator Development Studio in either a Call Adapter activity or an Assign activity. In a Call Adapter activity, the adapter request is defined by the following ways in the Properties tab of the Activity Property window:

16

BMC Atrium Orchestrator Base Adapters User Guide

Actor adapter requests

Static value: specifies the XML text of the request that you enter in the adapters Data field, exactly as shown in the templates and the samples provided in this

guide.
s

Context key: specifies that an Assign activity is used to create an XML document for

the adapter request and assigns that document to a context item. The context item is referenced in the Properties tab of the Call Adapter activity. This XML document must be contained within <request-data> tags. These tags are not included in the XML templates and the samples provided in this guide. You must add them to create a request that executes successfully. Some adapters can perform more than one type of action, so you must specify the action in the Action field of the Properties tab. For each adapter, this guide includes the available actions, a table outlining XML request elements, an XML template of the request, and a sample of XML adapter request. The BMC Atrium Orchestrator Development Studio User Guide contains detailed steps about using the Call Adapter and Assign activities.

Chapter 1 Overview of base adapters

17

Actor adapter requests

Table 1 describes the fields associated with each available option in the Properties tab for a Call Adapter activity. Table 1
Fields Adapter Name

Call Adapter activity propertiesstatic value as the adapter input (part 1 of 2)

Description Specifies the adapter to use to service the request It must be an adapter that has been configured in Grid Manager.

Peer Location

Specifies the location of the peer that services the adapter request The adapter must be enabled on the peer that services the request. This can be a different peer from the one that is executing the process. Following are the options:
s

any: Specifies that the adapter request can be serviced by any peer on the grid. The master job processor distributes the process to the next available peer. The adapter must be enabled on at least one peer on the grid. this: Specifies that the adapter request is serviced by the selected peer and contains the master job processor. With this option, The adapter must be enabled on the configuration distribution peers (CDPs) and all the activity peers (APs) on the grid because any one of them can be the master job processor at any time. Lightweight activity peers (LAPs) cannot become the master job processor. best: Allows the grid to determine the best peer to service the request. The adapter must be enabled on at least one peer on the grid.

peer: Enables you to specify the peer to service the adapter request. The adapter must be enabled on the peer specified in the Peer Name field. Peer Name Specifies the peer on the grid on which the adapter is enabled This element is required when the value of <Peer Location> is peer. Action Specifies the type of action to be performed by the adapter request Not all adapters use an adapter action. If an adapter does not have an associated action, leave this field blank.

18

BMC Atrium Orchestrator Base Adapters User Guide

Actor adapter requests

Table 1
Fields

Call Adapter activity propertiesstatic value as the adapter input (part 2 of 2)

Description Specifies an XML document that defines the adapter request The samples and the templates for each adapter can be referenced in this document. You can enter the templates provided in this document into the Adapter Data field exactly as shown.

Adapter Data

Adapter Input

Specifies, for the Context key option, a context item that contains an XML document with a root element, <requestdata>, for the adapter request Click the browse icon to launch the Context Browser and select a context item, the value of which must contain the <request-data> element and all required elements for the adapter request. The specific XML required for each adapter can be referenced in this document. If you select a global context item, the globe icon is displayed.

Adapter Output

Specifies the context item to which the adapter response is assigned Not all adapter requests produce an adapter response. If an adapter output is assigned for an adapter request that does not produce a response, the activity fails and a compensation is executed.

Each adapter request consists of the elements shown in Table 2. The complete adapter request is formed by the Call Adapter activity, which uses information provided in its Activity Property panel. The only XML content that you must provide is contained in the <request-data> element shown in Figure 1. Figure 1 XML sample of an adapter request

<adapter-request> <target-adapter>target_adapter_name</target-adapter> <peer-location> <location> this | any | best | peer </location> <peer-name>peer_name</peer-name> </peer-location> <request-action>adapter-specific request action text</request-action> <request-data>adapter-specific request XML data</request-data> </adapter-request>

Chapter 1 Overview of base adapters

19

Actor adapter responses

Table 2 describes the actor adapter request elements. Table 2

<targetadapter> <peerlocation> <location>

Actor adapter request elements

Description Specifies the adapter name as defined in Grid Manager Contains information about which peer to use to execute the adapter request Specifies the type of peer from which the adapter request executes: this, any, best, peer For description of these values, see Table 1 on page 18. An adapter request can be executed on a peer different from the one that executes the process that initiates the adapter request. Required Yes Yes Yes

Request element

<peer-name>

Specifies the peer name This element is used only when the value of <location> is peer.

Yes

<requestaction> <requestdata>

Specifies the action that the request executes Specifies an XML document that provides the adapter with specific instructions and parameters to facilitate an action

No No

Actor adapter responses

An actor adapter response contains the result returned by an actor adapter request. The contents of the response vary by adapter, and not all adapters produce a response. The response can be assigned to a context item. In BMC Atrium Orchestrator Development Studio, you must enter this context item in the Adapter Output field of the ctivity Property window of the Call Adapter activity. By assigning the adapter response to a context item, you make the response available to subsequent activities in the process. If an adapter output is assigned to an adapter request that does not produce a response, the activity fails and a compensation is executed. For each actor adapter that generates an adapter response, this guide includes the sample adapter responses. For detailed information about configuring activities and building workflows, see the BMC Atrium Orchestrator Development Studio User Guide.

20

BMC Atrium Orchestrator Base Adapters User Guide

Monitor adapter events

Monitor adapter events

Monitor adapters generate events for specific occurrences of detected actions in external systems. The criteria for event generation are defined in the adapter's configuration node in Grid Manager. Monitor adapters generate events when they are enabled on an active peer and an external incident occurs that warrants an event notification. Figure 2 shows a sample event for a monitor adapter. Figure 2 XML sample of a monitor adapter event

<adapter-event> <source-adapter>adapter-name</source-adapter> <event>event text</event> <data>event XML data</data> </adapter-event>

Each adapter event contains XML elements as indicated in Table 3. Table 3 Monitor adapter event elements
Description Specifies the adapter name as configured in Grid Manager Specifies the text that summarizes an event, a description of the event Contains the adapter specific response The contents of this element vary depending on the adapter.

Request elements <source adapter> <event> <data>

Rules are created in BMC Atrium Orchestrator Development Studio, within the rules designer for a module, to evaluate these events. For monitor adapter events that meet the module's rule criteria, a process is triggered. For detailed instructions for creating rules for a module, see the BMC Atrium Orchestrator Development Studio User Guide. To use the data from the monitor adapter event in the triggered process, create a job input parameter on the Start activity of the workflow. The content of the <data> element from the monitor adapter event automatically populates this input.

Chapter 1 Overview of base adapters

21

Monitor adapter events

22

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

Terminal adapter features

A terminal adapter is a communication or an interface between a computer and an integrated services digital network line. The adapter enables you to host multiple client sessions simultaneously. Base adapters that share some common features and functionality and are classified as terminal type adapters are:
s s s s s s s s s

File Command Line SSH Kerberized SSH Telnet SCP FTP SFTP PowerShell

This chapter describes the common features of terminal adapters. While each feature is described individually, you can combine them as needed in a single request, if they are all supported. This chapter presents the following topics: Multiple configuration nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attributes for specifying directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attribute for specifying a timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FAT commands to enable platform independence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command attribute for continuing execution after a command failure . . . . . . . . . . . Command attribute for disabling line-termination character . . . . . . . . . . . . . . . . . . . . Command attribute for ignoring a command response. . . . . . . . . . . . . . . . . . . . . . . . . 24 25 26 27 27 30 30 31 31 32

Chapter 2

Terminal adapter features

23

Multiple configuration nodes

Command attribute for using a special character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Persistent connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Proxy commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Known hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Public key authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Verification of OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Character set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Command group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 env-variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 executable directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Terminal adapters feature overview table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Multiple configuration nodes

The multiple configuration nodes feature enables a single adapter configuration to have multiple remote hosts defined. Each configuration node designates the connection criteria for a specific remote host. The first configuration node is the default configuration node. If you do not assign a value to the first node, default is used. A name is mandatory for additional nodes. The following adapters support multiple configuration nodes:
s s s s s s s s

SSH Kerberized SSH Telnet SCP FTP SFTP Windows Command PowerShell

In the adapter request, the configuration node names are referred to as target names. Figure 3 provides an XML sample of an adapter configuration with multiple nodes. Figure 3
<configs>
<config name="config-one"> <>adapter-specific element1</> <>adapter-specific element2</> </config> <config name="config-two"> <>adapter-specific element3</>you have a config element <>adapter-specific element4</> </config> </configs>

XML sample of an adapter configuration with multiple nodes

24

BMC Atrium Orchestrator Base Adapters User Guide

Dynamic Targets

NOTE
The <configs> element is optional, but BMC recommends that you use it when more than one <config> node is defined.

Dynamic Targets
The dynamic targets feature enables you to define the connection information for a remote host within an adapter request. With the use of dynamic targets, you can configure an adapter in Grid Manager with a configuration node, <config/>, and designate the configuration node in each adapter request. Alternatively, an adapter configuration can contain a fully defined configuration node and have a dynamic target defined for selected adapter requests. The following adapters support dynamic targets:
s s s s s s s s

SSH Kerberized SSH Telnet SCP FTP SFTP Windows Command PowerShell

In an adapter request, you can designate the target information using the following methods. You can combine these methods in a single request for multiple targets. The commands provided in an adapter request are executed on each target designated in that request.
s

Method 1: To designate a specific target that has been defined in the adapter configuration, use the elements shown in the request in Figure 4. XML sample of a specific target

Figure 4

... <targets> <target name="config name"/> </targets> ...

Method 2: To use all the targets defined in the adapter configuration, use the elements shown in the request in Figure 5.

Chapter 2

Terminal adapter features

25

Command attributes for specifying directories

Figure 5

XML sample of all defined targets

... <targets> <target name="all"/> </targets> ...

Method 3: To define a dynamic target within a request, use the elements shown in the request in the Figure 6. XML sample of a dynamic target

Figure 6

... <targets> <target> <!--adapter-specific target elements --> </target> </targets>

When defining a dynamic target in an adapter request, you must provide all the required target elements in the request. With a dynamic target, partial target information cannot be retrieved from the adapter configuration. A target is either defined completely in the configuration or in the adapter request.

Command attributes for specifying directories

Command Line and Windows Command adapter requests contain <command> elements that can use the following optional attributes to specify directories for command execution or script location. Table 4 describes the command attributes for directories. Table 4
Attribute <working-dir>

<Command> attributes for directories

Description Specifies the directory where the command is executed If this attribute is not specified, the command executes in the $AO_HOME directory. This attribute is not valid for the Windows Command adapter.

<command-dir>

Specifies the directory in which the script is located If this attribute is not specified, the script must be located in the current directory.

26

BMC Atrium Orchestrator Base Adapters User Guide

Command attribute for specifying a timeout

In the Command Line adapter sample XML request shown in Figure 7, the command executes in the /usr/executionDir directory, using a script from the /usr/scriptDir directory. Figure 7 XML sample of <command> attributes for directories

... <commands> <command working-dir="/usr/executionDir" command-dir="/usr/scriptDir">MyScript.sh </command> </commands> ...

Command attribute for specifying a timeout

Command Line, SSH, Kerberized SSH, Telnet, SCP, FTP, SFTP, and Windows Command adapters can use the timeout-secs attribute in a <command> element to define the time, in seconds to wait after the execution of a command for a prompt to be returned after the successful execution of a command. This delay can prevent the request from becoming unresponsive, especially in cases where the prompt returned is different from the expected prompt. The default-value of timeout-secs is 60. In the XML sample shown in Figure 8, if the prompt is not returned within 90 seconds, the adapter response is an error message indicating that a timeout occurred. Figure 8 XML sample of a command attribute for timeout

... <commands> <command timeout-secs="90">pwd</command> </commands> ...

FAT commands to enable platform independence

Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters use a FAT command that enables the creation of platform-independent adapter requests. The <fat-command> element contains multiple <command> elements, each containing a value that has syntax specific to a system type and an optional system version. The os-id and os-version attributes define the platform.

Chapter 2

Terminal adapter features

27

FAT commands to enable platform independence

Valid values for the os-id element are:

s s s s s s s

Windows Server 2008 Windows NT Windows 2000 Windows 2003 Windows XP Windows Default Linux

s s s s s s s

MacOS AIX HP-UX Cisco IOS JunOS F5 TM OS SunOS

During the execution of the adapter request, the adapter compares the value of the
os-id (and os-version if provided) command attributes with the target system's

type and version and executes the command that provides an exact match. If any of the os-ids in the <fat-command> element do not match with the target Windows OS, the adapter will search for the command where the os-id is Windows Default and execute the command for this os-id. If no exact match is found and Windows Default is not specified as an os-id, the adapter request is not executed and a compensation, if defined, is executed.

NOTE
If you specify Windows Default as the os-id, you must not use the os-version attribute in the adapter request.

Like standard command elements, you can use multiple FAT command elements in a single adapter request. The XML sample shown in Figure 9 uses the ping command to send five requests to server1. Only one command is executed, based on the operating-system type of the computer executing the command. If the operating-system type does not match any of the types provided, a compensation, if defined, is executed. Figure 9 XML sample of a FAT command

... <commands> <fat-command> <command os-id="Windows 2003">ping -n 5 server1</command> <command os-id="SunOS" os-version="5.8">/usr/sbin/ping -s server1 565</command> <command os-id="Linux">/bin/ping -c 5 server1</command> </fat-command> </commands> ...

28

BMC Atrium Orchestrator Base Adapters User Guide

FAT commands to enable platform independence

You can define more then one FAT command for each operating system. When you do that, you use a <commands> element to contain the <command> elements to be executed for a single operating system. You use the os-id and os-version attributes of the <commands> element. Additional attributes added to the <commands> element apply to the child <command> elements. In addition to the attributes in the <commands> element, each command can have individual attributes defined. When using the multiple command structure, you can define only the os-id and osversion as attributes of the <commands> element. You can use all other valid command attributes on either the <commands> or <command> elements. If you specify an attribute in both the <commands> and the <command> elements, the attribute value in the <command> element takes precedence. Figure 10 illustrates the options available with the multi-command structure for FAT commands. For the Linux commands, the first command has a timeout of 90 seconds and the second command has a timeout of 120 seconds. Figure 10 XML sample of a multi-command structure for FAT commands

... <commands> <fat-command> <commands os-id="Windows 2003" command-dir="/usr/scriptDir"> <command continue-on-failure='true'>command 1</command> <command>command 2</command> </commands> <commands os-id="SunOS" os-version="5.8"> <command>command 1</command> <command ignore-exit-code="true">command 2</command> <command>command 3</command> </commands> <commands os-id="Linux" timeout-secs="120"> <command timeout-secs="90">command 1</command> <command>command 2</command> </commands> </fat-command> </commands> ...

Figure 11 shows an XML sample of FAT commands with Windows Default as the value for the os-id attribute. Figure 11 XML sample of FAT commands with Windows Default as the value for the os-id attribute

<commands> <fat-command> <commands os-id="Windows 2003"> <command>ipconfig</command> </commands> <commands os-id="Windows 2000"> <command>dir</command> </commands> <commands os-id="Windows Default"> <command>hostname</command> </commands> </fat-command> </commands>

Chapter 2

Terminal adapter features

29

Password encryption

Password encryption
SSH, Kerberized SSH, Telnet, SCP, FTP, SFTP, Windows Command, and PowerShell adapters can use an encryption-type attribute with the <password> element. You can use this attribute in the adapter configuration or in a dynamic target in an adapter request. If no encryption-type is specified, the value is considered to be unencrypted (Plain). The encryption-type value is not case sensitive. The valid values for encryption-type are Base64 and Plain. Figure 12 shows an XML sample of an SSH dynamic target using the Base64 option with an encrypted password. Figure 12 XML sample of SSH dynamic target using the Base64 option

... <targets> <target> <host>server1</host> <port>2200</port> <user-name>user1</user-name> <password encryption-type="Base64">cGFzczE=</password> <prompt>pr1</prompt> <timeout-secs>120</timeout-secs> </target> </targets> ...

Command encryption
Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters can use an encryption-type attribute with the <command> element. The valid values for encryption-type are Base64 (or base64) or Plain (or plain). If no encryption-type is specified, the value is considered to be unencrypted (Plain). Figure 13 shows an XML sample of a command using the Base64 option with an encrypted password. Figure 13 XML sample of a command using the Base64 option

... <commands> <command encryption-type="base64">bHM=</command> </commands> ...

30

BMC Atrium Orchestrator Base Adapters User Guide

Command attribute for continuing execution after a command failure

Command attribute for continuing execution after a command failure

Command Line, SSH, Kerberized SSH, Telnet, Windows Command, and PowerShell adapters can use a continue-on-failure attribute with the <command> element. With this attribute set to true, if a command fails to execute, the subsequent command is executed. In the absence of this attribute, or if this attribute is set to false, if a command fails to execute, the adapter response is an error message and subsequent commands are not executed. Figure 14 shows an XML sample of the continue-on-failure attribute. Figure 14 XML sample of continue-on-failure attribute

... <commands> <command continue-on-failure="true">first command</command> <command>second command</command> <command>third command</command> </commands> ...

Command attribute for disabling linetermination character

Command Line, SSH, Kerberized SSH, Telnet, and Windows Command adapters can use a disable-line-termination attribute with the <command> element. You can use this attribute for menu commands that need to be sent as a single character without any line termination. With this attribute set to true, the command is sent without any termination character. In the absence of this attribute, or with this attribute set to false, the specified or default (\n) line termination character is sent with the command. Figure 15 shows an XML sample of the disable-line-termination attribute. Figure 15 XML sample of disable-line-termination attribute

... <commands> <command disable-line-termination="true">CTRL-D</command> </commands> ...

Chapter 2

Terminal adapter features

31

Command attribute for ignoring a command response

Command attribute for ignoring a command response

SSH, Kerberized SSH, Telnet, and PowerShell adapters can use an ignore-response attribute with the <command> element. Use this attribute to skip the processing of a response to a command. With this attribute set to true, any command response is ignored and the next command (if any) is executed. The ignored response appears in the response for the subsequent command. Typically, you would use this attribute when you issue an exit command is issued to log out of a shell. In the absence of this attribute, or with a value of false, any command response is processed normally. Figure 16 shows an XML sample of the ignore-response attribute. Figure 16 XML sample of ignore-response attribute

... <commands> <command ignore-response="true">exit</command> </commands> ...

Command attribute for using a special character

Command Line, SSH, Kerberized SSH, Telnet, and Windows Command adapters can use an is-special-character attribute with the <command> element. You can use this attribute to define a command for Escape (ESC), Line Feed (LF), or Carriage Return (CR) by setting it to true. In the absence of this attribute, if you set it to false, you can specify any valid OS command. Figure 17 shows an XML sample of the is-special-character attribute. Figure 17 XML sample of is-special-character attribute

... <commands> <command is-special-character="true">ESC</command> </commands> ...

32

BMC Atrium Orchestrator Base Adapters User Guide

Persistent connectivity

Persistent connectivity
SSH, Kerberized SSH2, Telnet, SCP, FTP, SFTP, and Session-based CLI adapters can use a feature that permits a connection to persist for multiple requests within a process. A connection is named when established, and subsequent requests can specify this named connection to be reused for a request. The connection remains available until the end of the process, or until the connection is terminated with a <terminate-on-exit> element. The named connection is defined in an adapter request within the <target> block by using a <connection> block that contains a <name> tag and a <terminate-on-exit> tag. The <name> tag is required. The <terminate-on-exit> tag is optional, and its default value is false, maintaining the connection. The SSH, SCP, FTP, and SFTP adapters also contain a <connection-ttl> tag that specifies the time (in seconds) for which a named connection should persist. The named connection is an optional function. If there is no <connection> block, the connection opens and closes within the request and must be reopened for each subsequent request of that target. Figure 18 shows an XML sample of a named connection used in conjunction with a dynamic target. This connection terminates upon completion of the request. Figure 18 XML sample of a named connection used in conjunction with a dynamic target

... <target> <host>sample.target1.com</host> <port>23</port> <user-name>user1</user-name> <password>pass1</password> <prompt>user1$</prompt> <connection> <name>target1_connection</name> <connection-ttl>xx</connection-ttl> <terminate-on-exit>true</terminate-on-exit> </connection> </target> ...

When using a named connection with a dynamic target, you must define the dynamic target completely in each request. You cannot reference its as a name attribute with the <target> in subsequent requests. Only targets defined in the adapter configuration can be referenced with a name attribute in an adapter request.

Chapter 2

Terminal adapter features

33

Proxy commands

Figure 19 shows an XML sample of a named connection used in conjunction with a target name reference from the adapter configuration. In the absence of the <terminate-on-exit> element, this connection remains open upon completion of the request. Figure 19 XML sample of a named connection in conjunction with a target name reference

... <target name="target2"> <connection> <name>target2_connection</name> </connection> </target> ...

Each subsequent request that uses a named connection is configured in the same manner, with either a complete dynamic target or a target name reference to the adapter configuration that contains a <connection> block. The connection is reused if open, or reestablished if it has been closed. Connections can persist to called processes below the primary process layer. The connection is terminated at the endpoint of the primary process layer.

Proxy commands
SSH, Kerberized SSH, and Telnet adapters can use a pass-through function for command execution that enables you to connect to a secondary target from the initial host by using Telnet or SSH. With this connection, you can execute commands on the secondary target.

NOTE
To use this functionality with SSH, you must use prompts. With unprompted SSH, each command is executed independently, not successively, as is needed to log on to the remote host. Additional options assist the command execution on secondary targets. Commands issued on a secondary host can be contained in <command-group> tags. The command has an optional attribute, verify-os, which you can use to obtain the operating system type and version on the secondary host. This is an important function if FAT commands are used and the operating system on the secondary system is different from the initial host.

34

BMC Atrium Orchestrator Base Adapters User Guide

Known hosts

The ignore-exit-code attribute of the <command> element prevents an exit code from being obtained after executing the command. By default, an exit code request is issued after each command. This can cause problems if the retrieval of an exit code is interpreted as a user name, password, prompt, or other input during the authentication process. You must use this attribute when the command that is automatically issued to obtain an exit code could be misinterpreted and would interfere with subsequent commands. As with all <command> elements, the prompt attribute indicates the expected prompt returned upon execution of the command. The subsequent command is executed at this returned prompt. Prompts specified in a <command> attribute are typically defined in a <prompts> block in the request. If a prompt not defined in the <prompts> block is used as an attribute value for a <command>, the actual attribute value is used as the prompt. In the following example, if a value for prompt1 has not been defined in the <prompts> block, prompt1 is used as the prompt for the command:
<command prompt="prompt1">command 1</command>,

Figure 20 shows an XML sample of a request that uses the proxy command features. Figure 20 XML sample of a request that uses the proxy command features

... <prompts> <prompt name="login">login:</prompt> <prompt name="password">password:</prompt> </prompts> <commands> <command prompt="login" ignore-exit-code="true">telnet test.target1.com</command> <command prompt="password" ignore-exit-code="true">user1</command> <command ignore-exit-code="true">pass1</command> <command-group verify-os="true"> <command>cd /tmp</command> <command>ls -al</command> <command>ps</command> <command>exit</command> </command-group> <command>exit</command> </commands> ...

Known hosts
SSH, SCP, and SFTP adapters use functions that verify the encryption key when opening a connection. Table 5 describes optional elements that you can use in both adapter configurations and dynamic targets to verify the encryption key when opening a connection.

Chapter 2

Terminal adapter features

35

Public key authentication

Table 5
Element

Optional elements for verifying the encryption key

Description Identifies the path to the local known_hosts file This file is used when verifying the key. Default value: homeDir/.ssh/known_hosts.

<known-hostsconfig>

<allow-unknownhosts>

Specifies whether a connection must continue if the key verification fails Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.

<preferred-pkalgorithm>

Specifies the preference of the algorithm used to encrypt the public key Valid values: ssh-dss, ssh-rsa (default)

Figure 21 shows an XML sample using the optional elements described in Table 5 on page 36. Figure 21 XML sample configuration for known hosts

.. <target> <host>test.target1.com</host> <port>22</port> <user-name>user1</user-name> <password>password1</password> <prompt>user1$</prompt> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> </target> ...

Public key authentication

SSH, SCP, and SFTP adapters can use public-key-based authentication when servicing adapter requests. This feature is an alternative to password-based authentication. To use public key authentication, define the file location of the SSH key file and an associated pass phrase. Table 6 describes optional elements that you can use for the adapter configuration and dynamic targets in the adapter requests. The default authentication method is password-based; if a <password> element is present in an adapter configuration or the dynamic target node of an adapter request, password authentication is used, regardless of the presence of <private-key-file> and <pass-phrase> elements. If the <password> element is omitted, the <privatekey-file> and <pass-phrase> elements are used.

36

BMC Atrium Orchestrator Base Adapters User Guide

Verification of OS

Table 6
Element

Optional elements for public key authentication

Description Identifies the path and the file name for the local SSH key file This file is used when performing public key authentication. This path and file must exist on the peer servicing the adapter request.

<private-keyfile>

<pass-phrase>

Identifies the pass phrase that protects the private key file This element can contain an attribute of encryption-type to indicate whether the pass phrase provided is encrypted. Valid values (encryption type): Base64, Plain (default) (unencrypted)

Figure 22 shows an XML sample using the optional elements described in Table 6 on page 37. Figure 22 XML sample of public key authentication optional elements

... <target> <host>test.target1.com</host> <port>22</port> <user-name>user1</user-name> <private-key-file>/usr/home/user1/.ssh/id_dsa<private-key-file> <pass-phrase encryption-type="Base64">cGFzcyBwaHJhc2U=</pass-phrase> <prompt>user1$</prompt> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> </target> ...

Verification of OS
Command Line, SSH, Kerberized SSH, and Telnet adapters can use a <verify-os> element in the adapter configuration or in a dynamic target definition within the adapter request. This element determines whether the adapter must determine the target OS type soon after authentication is complete or a connection is established. This element has a default value of true, indicating that the OS is verified. If the OS is verified, exit codes are returned by the executed commands. If the element is present with a value of false, the OS is not verified and none of the commands executed return an exit code.

Chapter 2

Terminal adapter features

37

Character set

Figure 23 shows an XML sample using the <verify-os> element in an adapter configuration. Figure 23 XML sample of <verify-os> element in an adapter configuration

<config> ... <verify-os>false</verify-os> ... </config>

Character set
Character sets are identifiers that describe a series of universal characters. The following adapters can use a <character-set> element in the adapter configuration or in a dynamic target definition within the adapter request:
s s s s s s s s s

FTP JMS Actor JMS Monitor File Adapter Command Line SSH Telnet FTP SFTP

Figure 24 shows an XML sample using the character-set element in an adapter configuration. Figure 24 XML sample of the

<config> <character-set>Shift_JIS</character-set> </config>

Command group
The <command-group> tag has an optional attribute, in which multiple commands can be executed in the group. This is an important function if you use FAT commands and the operating system on the secondary system is different from the initial host. The Command line adapter supports this feature.

38

BMC Atrium Orchestrator Base Adapters User Guide

env-variables

Figure 25 shows an XML sample using the command-group feature in an adapter request. Figure 25 XML sample of the command-group feature in an adapter request

<command-request> <commands> <command-group> <command run-as="true" user-name="guest2" password="abc123">notepad.exe</command> </command-group> </commands> </command-request>

env-variables
Env-variables specify environment variables (name-value pairs). The Command line adapter supports this feature. Figure 26 shows an XML sample using the env-variables feature in an adapter request. Figure 26 XML sample of the env-variables feature in an adapter request

<adapter-request> <env-variables> <env-variable> <name>New_Variable11</name> <value>New_varaible11_value</value> </env-variable> </env-variables> </adapter-request>

executable directory
Executable directory specifies the complete path to the directory in which the <executable> element is located. The Windows Command line adapter supports this feature. The default path is the same as the location of the adapter libraries:
$AO_HOME/server/Grid/library/adapters/roadapter-windows-command-[version].

This element is applicable in default mode only.

Chapter 2

Terminal adapter features

39

Terminal adapters feature overview table

Figure 27 shows an XML sample using the executable-directory feature in an adapter configuration. Figure 27 XML sample of the executable-directory feature in an adapter configuration

<config> <target>10.128.248.89</target> <user-name>admin</user-name> <password>adminpass</password> <logon-with-user-credentials>true</logon-with-user-credentials> <protocol>xcmd</protocol> <executable-directory>C:\ABCD\CDP\server/Test1/library/adapters/roadapter-windowscommand-7.6.05</executable-directory> <executable>xCmd.exe</executable> <escape-double-quotes>true</escape-double-quotes> <script-file-path>C:\test.bat</script-file-path> <max-request-queue-size>20</max-request-queue-size> <debug-utility>true</debug-utility> </config>

Terminal adapters feature overview table

Table 7 provides a quick reference of the features available for each terminal adapter. Table 7
Feature Multiple configuration nodes Dynamic targets Command attribute (working-dir) Command attribute (command-dir) Command attributes (timeout-secs) FAT command Password attributes (encryption-type) Command attributes (encryption-type) Command attributes (continue-on-failure) Command attributes (disable-linetermination) Command attributes (ignore-response)

Terminal adapter feature overview

Command File Line SSH N N N N N N N N N N N N Y Y Y Y N Y Y Y Y Y N N Y Y Y Y Y Y Kerberized SSH Telnet SCP Y Y N N Y Y Y Y Y Y Y Y N N Y Y Y Y Y Y Y Y N N Y N Y N N N FTP Y Y N N Y N Y N N N Windows SFTP Command PowerShell Y Y N N Y N Y N N N Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y Y Y Y N

40

BMC Atrium Orchestrator Base Adapters User Guide

Terminal adapters feature overview table

Table 7
Feature

Terminal adapter feature overview

Command File Line SSH N N N N N N Y N N N Y N N N N Y Y Y Y N Y Y Y Y Y Y Y N N N Kerberized SSH Telnet SCP Y Y Y N N Y N N N N Y Y Y N N Y Y N N N N N N N Y N Y Y Y N Y N N N FTP N Y N N Windows SFTP Command PowerShell N Y N Y Y N Y N N N Y N N N N N N N N Y N N N N N N N N N N

Command attributes (is-special-character) Persistent connectivity Proxy commands Known hosts Public key authentication Verification of OS Character set Command group Env variables Executable directory

NOTE
In Linux environments, BMC recommends that you set the value of the color attribute to none with a command to prevent erroneous control characters in the command output (<command>ls--color=none</command>)

Chapter 2

Terminal adapter features

41

Terminal adapters feature overview table

42

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

Using Terminal adapters

This chapter presents the following topics: File adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 File adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 File adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 File adapter request with read action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 File adapter response with read action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 File adapter request with write action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 File adapter response with write action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 File adapter request with append action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 File adapter response with append action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 File adapter request with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 File adapter response with a delete action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Command Line adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Command Line adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Command Line adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Command Line adapter requestUNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Command Line adapter requestMicrosoft Windows . . . . . . . . . . . . . . . . . . . . . 63 Command Line adapter responseWindows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Session-based CLI adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Windows Session-based CLI adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . 74 UNIX Session-based CLI adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Session-based CLI adapter requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . 77 run-as support in Command Line adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 SSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 SSH adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 SSH adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 SSH adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 SSH adapter keyboard-interactive capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 SSH KBI adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 SSH KBI adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 SSH KBI adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Kerberized SSH adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Kerberized SSH adapter (Java client)adapter configuration. . . . . . . . . . . . . . . 119 Kerberized SSH adapter (Java client)adapter request . . . . . . . . . . . . . . . . . . . . 122 Kerberized SSH adapter (Java client)adapter response . . . . . . . . . . . . . . . . . . . 125
Chapter 3 Using Terminal adapters 43

Kerberized SSH adapter (local client)adapter configuration. . . . . . . . . . . . . . . 129 Kerberized SSH adapter (local client)adapter request . . . . . . . . . . . . . . . . . . . . 131 Kerberized SSH adapter (local client)adapter response. . . . . . . . . . . . . . . . . . . 135 Telnet adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Telnet adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Telnet adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Telnet adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SCP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 SCP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 SCP adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SCP adapter request with get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SCP adapter response with get action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 SCP adapter request with put action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 SCP adapter response with put action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 FTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 FTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 FTP adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 FTP adapter request with a dynamic target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 FTP adapter response with a dynamic target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 FTP adapter request with append command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 FTP adapter response with append command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 FTP adapter request with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 FTP adapter response with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 FTP adapter request with cdup command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 FTP adapter response with cdup command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 FTP adapter request with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 FTP adapter response with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 FTP adapter request with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 FTP adapter response with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 FTP adapter request with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 FTP adapter response with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 FTP adapter request with mode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 FTP adapter response with mode command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 FTP adapter request with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 FTP adapter response with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 FTP adapter request with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 FTP adapter response with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 FTP adapter request with rename command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 FTP adapter response with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 FTP adapter request with rm command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 FTP adapter response with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 FTP adapter request with rmdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 FTP adapter response with rmdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 FTP adapter request with stat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 FTP adapter response with stat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 FTP adapter request with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 FTP adapter response with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . . 213 SFTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 SFTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

44

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chgrp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chgrp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chmod command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chmod command . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with chown command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with chown command. . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with get command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with get-dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with get-dir command. . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with lcd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with lcd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with lpwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with lpwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with ls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with mkdir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with mkdirs command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with mkdirs command . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with put command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with put-dir command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with put-dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with pwd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with rename command . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with rm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with symlink command . . . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with symlink command . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter request with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . . SFTP adapter response with multiple commands . . . . . . . . . . . . . . . . . . . . . . . . . Windows Command adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows Command adapter post-installation steps. . . . . . . . . . . . . . . . . . . . . . . Windows Command adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows Command adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows Command adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter post-installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell adapter response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

221 222 225 226 230 231 235 236 240 241 245 246 250 251 255 256 260 261 265 267 271 272 275 277 281 282 286 287 291 292 296 297 300 302 306 307 308 312 313 314 317 321 325 327 328 330 333

Chapter 3 Using Terminal adapters

45

File adapter

File adapter
The File adapter is an actor adapter that performs read, write, append, and delete functions on a file. Using a file name and action (read, write, append, or delete) arguments, the File adapter performs the specified action on the specified file, and in the case of write and append, using the lines provided. The File adapter does not need a configuration node but, you must configure the adapter in Grid Manager.

NOTE
The File adapter performs actions on the peer that executes the process. You cannot designate remote hosts for File adapter requests.

File adapter configuration

The File adapter does not require a configuration node, but the <config/> XML element is needed for the Properties field in Grid Manager adapter configuration. Adapter type: ro-adapter-file[version] Default adapter name: FileAdapter Figure 28 shows an XML sample of an adapter configuration for the File adapter. Figure 28
<config/>

XML sample of the File adapter configuration

Available actions File adapter request File adapter request with read action File adapter request with write action File adapter request with append action File adapter request with a delete action File adapter response with read action File adapter response with write action File adapter response with append action File adapter response with a delete action

46

BMC Atrium Orchestrator Base Adapters User Guide

File adapter request

File adapter request

The File adapter uses one of the four actions, read, write, append, or delete. The File adapter requests and responses are action-specific. The samples and the templates for each action supported by the File adapter are detailed in the following sections. You can specify the required action in the adapters Action field of the property panel for the Call Adapter activity. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

File adapter request with read action

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 8 describes the adapter request elements for the File adapter with read action. Table 8
Element <filename>

Adapter request elements for the File adapter with read action
Description Specifies the absolute path, including the file name, of the file to be read Required Yes No

<character- Specifies the supporting CharSet set> CharSet is also called Character Set that includes identifiers describing a series of universal characters <filetype> Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters <tokenize> Specifies the elements that provide the tokenization details If no value is provided, no tokenization occurs. To use the <tokenize> block, the <filetype> value must be TEXT. <delimiter> Specifies the character used to mark the separation of fields on a line This element is required when the tokenize element is used. Special characters must be preceded by a \ to avoid XML parsing errors. See Table 9 for the samples. This element is required with the <tokenize> element. <header> Determines whether the first line of the file is to be treated as a header Valid values: true, false (default)

No

No

Conditional

No

Chapter 3 Using Terminal adapters

47

File adapter request with read action

Table 9 lists the sample delimiter formats that are valid for the File adapter. Table 9
Delimiter tab pipe asterisk dash comma semi colon underscore dollar sign

Sample delimiter formats

Format \t \| \* \, or \, ; or \; _ or \_ \$

Figure 29 shows an XML template of the adapter request for a File adapter with read action. Figure 29 XML template of the File adapter request with read action

<fileRequest> <filename></filename> <character-set></character-set> <filetype></filetype> <tokenize> <delimiter></delimiter> <header></header> </tokenize> </fileRequest>

Figure 30 shows a sample adapter request for the File adapter with read action. Figure 30 XML sample of the File adapter request with read action
<fileRequest> <filename>/tmp/readfile.txt</filename> <character-set>Shift_JIS</character-set> <filetype>text</filetype> <tokenize> <delimiter>,</delimiter> <header>true</header> </tokenize> </fileRequest>

48

BMC Atrium Orchestrator Base Adapters User Guide

File adapter response with read action

File adapter response with read action

The read action request for a File adapter returns an adapter response that contains the lines read by the adapter request. The possible formats depend on whether the request was executed on an XML file, included tokenization, or whether the tokenized lines included a header line. Tokenization is the process of breaking a stream of text up into meaningful elements called tokens. The sample responses are provided for each option. Each sample for a text file type uses the same sample data file provided. Table 10 describes the elements of a File adapter response to a request with read action. Table 10
Element <metadata> <status>

Elements of a File adapter response to a request with read actionXML file type
Description Contains the summary information for the request Indicates whether the command executed successfully Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output> <XML file>

Specifies the duration of the command execution, in milliseconds Contains the XML file that is read Specifies an XML document that comprises the specified XML type file

Figure 31 illustrates an XML response for the File adapter with read action. Figure 31 XML sample of the File adapter response with read actionXML file type

<file-output> <metadata> <status>success</status> <error>success</error> <execution-milliseconds>100</execution-milliseconds> </metadata> <output> <!--XML file contents, contained as a child node of the output tags--> </output> </file-output>

The following example illustrates an example of the text file used for File adapter response with read action.
name,IP,device D1,198.162.1.111,router D2,198.162.2.222,router

Chapter 3 Using Terminal adapters

49

File adapter response with read action

Table 11 describes the elements of a File adapter response to a request with read action and no tokenization. Table 11
Element <metadata> <status>

Elements of a File adapter response to a request with read action and no tokenization
Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output> <lines>

Specifies the duration of the command execution, in milliseconds Contains the details about the lines read Contains the lines read The count attribute specifies the total number of lines read.

<line>

Contains the text of the line read The number attribute indicates the sequence in which the line was read.

Figure 32 illustrates the adapter response for the File adapter with read action and no tokenization. Figure 32 XML sample of the File adapter response with read action and no tokenization

<file-output> <metadata> <status>success</status> <error>success</error> <execution-milliseconds>100</execution-milliseconds> </metadata> <output> <lines count="3"> <line number="1">name,IP,device</line> <line number="2">D1,198.162.1.111,router</line> <line number="3">D2,198.162.2.222,router</line> </lines> </output> </file-output>

50

BMC Atrium Orchestrator Base Adapters User Guide

File adapter response with read action

Table 12 describes the elements of a File adapter response to a request with read action and when the tokenization header is set to false. Table 12
Element <metadata> <status>

Elements of a File adapter response to a request with read action and tokenization header-false
Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output> <lines>

Specifies the duration of the command execution, in milliseconds Contains the details about the lines read Contains the lines read The count attribute specifies the number of lines read.

<line>

Contains the fields read The number attribute indicates the sequence in which the line was read.

<field>

Contains the values for each field in the line The name attribute indicates the sequence of the field on the line.

Chapter 3 Using Terminal adapters

51

File adapter response with read action

Figure 33 illustrates the adapter response for a File adapter with read action when the tokenization header is set to false and the delimiter is set to a comma. Figure 33 XML sample of the File adapter response with read action and header-false

<file-output> <metadata> <status>success</status> <error>success</error> <execution-milliseconds>100</execution-milliseconds> </metadata> <output> <lines count="3"> <line number="1"> <field name="field1">name</field> <field name="field2">IP</field> <field name="field3">device</field> </line> <line number="2"> <field name="field1">D1</field> <field name="field2">198.162.1.111</field> <field name="field3">router</field> </line> <line number="3"> <field name="field1">D2</field> <field name="field2">198.162.2.222</field> <field name="field3">router</field> </line> </lines> </output> </file-output>

Table 13 describes the elements of a File adapter response to a request with read action and the tokenization header set to true. Table 13
Element <metadata> <status>

Elements of a File adapter response to a request with read action and tokenization header-true (part 1 of 2)
Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output> <lines>

Specifies the duration of command execution, in milliseconds Contains the details about the lines read Contains the lines read The count attribute specifies the number of lines read.

52

BMC Atrium Orchestrator Base Adapters User Guide

File adapter request with write action

Table 13
Element <line>

Elements of a File adapter response to a request with read action and tokenization header-true (part 2 of 2)
Description Contains the fields read The number attribute indicates the sequence in which the line was read.

<field>

Contains the values for each field in the line The name attribute indicates the field name, based on the header (first) line.

Figure 34 illustrates the adapter response for the File adapter with read action and the tokenization header set to true. Figure 34 XML sample of the File adapter response with read action and header set to true

<file-output> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> <output> <lines count="2"> <line number="1"> <field name="name">D1</field> <field name="IP">198.162.1.111</field> <field name="device">router</field> </line> <line number="2"> <field name="name">D2</field> <field name="IP">198.162.2.222</field> <field name="device">router</field> </line> </lines> </output> </file-output>

File adapter request with write action

The write action request for a File adapter can be performed on text and XML files. To write any data to a file, the data must be specified in the <line> element in the adapter request. Table 14 describes the adapter request elements for File adapter with write action.

Chapter 3 Using Terminal adapters

53

File adapter request with write action

Table 14
Element

Adapter request elements for the File adapter with write action
Description Required Specifies the absolute path, including the file name, of the file to which lines Yes are written No

<filename>

<character- Specifies the supporting CharSet set> CharSet is also called Character set that includes identifiers describing a series of universal characters. <filetype> Specifies the type of file to be written Valid values: text (default), xml <lines> Contains the <line> elements This element is required if the value of <filetype> is text. <line> Specifies the text of the line to be written This element is required if the value of <filetype> is text.

No

Conditional

Conditional

Figure 35 shows an XML template for the File adapter request with write action for a TEXT file. Figure 35 XML template of the File adapter request with write actionTEXT file

<fileRequest> <filename></filename> <character-set></character-set> <filetype></filetype> <lines> <line></line> </lines> </fileRequest>

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. Figure 36 shows an XML template for the File adapter request with write action for an XML file. Figure 36 XML template of the File adapter request with write actionXML file

<fileRequest> <filename></filename> <character-set></character-set> <filetype>xml</filetype> <!--XML document--> </fileRequest>

Figure 37 shows a sample adapter request for the File adapter with write action for a TEXT file. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

54

BMC Atrium Orchestrator Base Adapters User Guide

File adapter response with write action

Figure 37

XML sample of the File adapter request with write actionTEXT file

<fileRequest> <filename>/tmp/writefile.txt</filename> <character-set>Shift_JIS</character-set> <filetype>text</filetype> <lines> <line>data to be written</line> ... </lines> </fileRequest>

Figure 38 shows a sample adapter request for the File adapter with write action for an XML file. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 38 XML sample of the File adapter request with write action XML file

<fileRequest> <filename>/tmp/writefile.txt</filename> <character-set>Shift_JIS</character-set> <filetype>xml</filetype> <!--The XML document to be written to the specified file--> </fileRequest>

File adapter response with write action

The write action request for a File adapter returns an adapter response containing the summary information for the request. A detailed output is not returned for this action. Table 15 describes the elements of a File adapter response to a request with write action. Table 15
Element <metadata> <status>

Elements of a File adapter response to a request with write action

Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output>

Specifies the duration of the command execution, in milliseconds Specifies the empty element that is returned There is no detailed output returned for a write action.

Chapter 3 Using Terminal adapters

55

File adapter request with append action

Figure 39 illustrates an XML sample of the adapter response for the File adapter with write action. Figure 39 XML sample of the File adapter response with write action

<file-output> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> <output/> </file-output>

File adapter request with append action

The append action can be performed on TEXT files. All the elements in the request must be defined to append the file. In the sample, the <lines> element is required. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. Figure 40 shows an XML template for the File adapter request with append action. Figure 40 XML template of the File adapter request with append action

<fileRequest> <filename></filename> <character-set></character-set> <lines> <line>data to be written</line> ... </lines> </fileRequest>

Table 16 describes the adapter request elements for the File adapter with append action. Table 16
Element <filename> <characterset>

Adapter request elements for the File adapter with append action
Description Specifies the absolute path, including the file name, of the file to which the lines are appended Specifies the supporting CharSet CharSet is also called Character set that includes identifiers describing a series of universal characters. Required Yes No

<lines> <line>

Contains the <line> elements Specifies the text of the line to be written

Yes No

56

BMC Atrium Orchestrator Base Adapters User Guide

File adapter response with append action

Figure 41 shows a sample adapter request for the File adapter with append action. Figure 41 XML sample of the File adapter request with append action

<fileRequest> <filename>/tmp/appendfile.txt</filename> <character-set>Shift_JIS</character-set> <lines> <line>data to be written</line> ... </lines> </fileRequest>

NOTE
If the specified file does not exist, the file is created, and the request appends the data in the <lines> element to the newly created file.

File adapter response with append action

The append action request for a File adapter returns an adapter response that contains the summary information for the request. A detailed output is not returned for this action. Table 17 describes the elements of a File adapter response to a request with append action. Table 17
Element <metadata> <status>

Elements of a File adapter response to a request with append action

Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output>

Specifies the duration of the command execution, in milliseconds Returns an empty element No detailed output is returned for an append action.

Chapter 3 Using Terminal adapters

57

File adapter request with a delete action

Figure 42 illustrates the sample adapter response for the File adapter with append action. Figure 42 XML sample of the File adapter response with append action

<file-output> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> <output/> </file-output>

File adapter request with a delete action

When you create the adapter request in the Transform Editor, you must enclose the request in <request-data> tags. The Delete action can be performed on any file. The absolute path of the file is required to delete a file through the Delete adapter request. Table 18 describes the adapter request elements for the File adapter with a delete action. Table 18
Element <filename>

Adapter request element for the File adapter with a delete action
Description Specifies the absolute path and file name of the file to be deleted Required Yes

Figure 43 shows a sample adapter request for the File adapter with a delete action. Figure 43 XML sample of the File adapter request with a delete action

<fileRequest> <filename>/tmp/filetodelete.txt</filename> </fileRequest>

File adapter response with a delete action

The delete action for the File adapter request returns an adapter response containing the summary information for the request. A detailed output is not returned for this action.

58

BMC Atrium Orchestrator Base Adapters User Guide

File adapter response with a delete action

Table 19 describes the elements of a File adapter response to a request with a delete action. Table 19
Element <metadata> <status>

Elements of a File adapter response to a request with a delete action

Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<executionmilliseconds> <output>

Specifies the duration of the command execution, in milliseconds Returns an empty element No detailed output is returned for a delete action.

Figure 44 illustrates the sample adapter response for the File adapter with a delete action. Figure 44 XML sample of the File adapter response with a delete action

<file-output> <metadata> <status>success or error</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> <output/> </file-output>

Chapter 3 Using Terminal adapters

59

Command Line adapter

Command Line adapter

The Command Line adapter executes shell commands. This adapter does not need a configuration node; it must be configured in Grid Manager. The Command Line adapter can use the following features of terminal adapters. For details about terminal adapter features, see Terminal adapter features on page 23.
s

Command attributes: working-dir command-dir timeout-secs FAT commandscommand attributes: encryption-type continue-on-failure disable-line-termination is-special-character ignore-exit-code os-id os-version Verification of OS

NOTE
The Command Line adapter might leave additional JVM processes on the Sun Solaris operating system. Delete these child JVM processes manually.

Command Line adapter configuration

Adapter type: ro-adapter-command-line[version] Default adapter name: CommandLineAdapter To configure the Command Line adapter, see Configuring the adapter on page 14.

60

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter request

Table 20 describes the adapter configuration elements for the Command Line adapter that you can specify by using the form view or XML view. Table 20
UI label Character Set

Configuration node elements of the Command Line adapter

Element Description Required No <character-set> Specifies the supporting CharSet CharSet is also called Character set that includes identifiers describing a series of universal characters. Default value: ISO-8859-2

Figure 45 shows an XML sample of the adapter configuration for the Command Line adapter. Figure 45 XML sample of the Command Line adapter configuration

<config> <character-set>Shift_JIS</character-set> </config>

You can also have an empty configuration as shown in Figure 46. Figure 46
<config/>

XML sample of the Command Line adapter with empty configuration

List of available actions Command Line adapter request Session-based CLI adapter Session-based CLI adapter requests and responses

Command Line adapter request

The Command Line adapter does not use an action. You must leave the adapters
Action field blank while configuring the activity properties for a call adapter activity

in BMC Atrium Orchestrator Development Studio. The following samples illustrate how special characters are handled in UNIX and Microsoft Windows environments. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 3 Using Terminal adapters

61

Command Line adapter requestUNIX

NOTE
The default working directory for the Command Line adapter is:
s s

Windows: Windows\System32 Linux or Solaris: $AO_HOME/bin

Command Line adapter requestUNIX

The commands must be specified like they are typed at the system prompt. The adapter prepends cmd/c or /bin/sh -c to the beginning of the command, as needed. When you create the adapter request in the Transform Editor, the template must be enclosed within <request-data> tags. Figure 47 shows an XML template for the Command Line adapter request (UNIX). Figure 47 XML template of the Command Line adapter requestUNIX sample

<command-request> <commands> <command working-dir="$AO_HOME/bin "></command> <command></command> </commands> </command-request>

Figure 48 shows a sample adapter request (UNIX) for the Command Line adapter. Figure 48 XML sample of the Command Line adapter requestUNIX sample

<command-request> <commands> <fat-command> <commands os-id="SunOS" working-dir="/export/home/dev "> <command>ls</command> </commands> <commands os-id="Linux" working-dir="/home/dev"> <command>ls</command> </commands> </fat-command> </commands> </command-request>

62

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter requestMicrosoft Windows

Command Line adapter requestMicrosoft Windows

In a Microsoft Windows environment, adapter requests use XML documents and need special formatting to handle the commands properly. Any directory or file name containing spaces must be enclosed in double quotation marks ( ). The backward slash (\) must be escaped with an additional \ when used as a command or an attribute value. If double quotation marks are used in an attribute, the attribute value must be enclosed within single quotation marks () (single quotes) instead of the standard . When you create the adapter request in the Transform Editor, the template must be enclosed within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

NOTE
You cannot execute commands for the Windows Command Line adapter by using a domain administration account that has local administration rights.

Table 21 describes the adapter request elements for the Command Line adapter. Table 21
Element <command>

Adapter request elements for the Command Line adapter

Description Specifies the command to execute Each command line can have optional attributes as described in Terminal adapter features on page 23. Required Yes Yes

<commands> Contains the <command> elements

<envSignifies more than one environment variable variables> <envvariable> <name> <value> Specifies a name-value pair for an environment variable Specifies the name of the environment variable to be set or cleared Specifies the corresponding value for a given environment variable name Note: The environment variable is cleared, if the value is empty or not specified.

No No No No

Figure 49 shows a sample Windows adapter request for the Command Line adapter.

Chapter 3 Using Terminal adapters

63

Command Line adapter responseWindows

Figure 49

XML sample of the Command Line adapter requestWindows sample

<command-request> <commands> <command>dir c:\\TempDirectory</command> <command>dir c:\\"Documents and Settings"</command> <command working dir="c:\\Windows\System32">dir</command> <command working dir='c:\\"Documents and Settings"'>dir</command> </commands> </command-request>

Command Line adapter responseWindows

The Command Line adapter returns an adapter response containing the results of the commands defined in the adapter request. Figure 45 illustrates a sample adapter response for the Command Line adapter. Figure 50 XML sample of the Command Line adapter response

<command-result> <response-metadata> <status>success</status> <error>Present only with status of 'error'</error> </response-metadata> <targets-output> <target-output> <target-metadata> <os-id>system type</os-id> <os-version>system version</os-version> <os-arch>system architecture</os-arch> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <command>ls -l</command> <working-dir>/</working-dir> <line-count>5</line-count> <execution-milliseconds>169</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <line index="1">total 12617</line> <line index="2">drwxrwxr-x 89 root admin 3026 4 Feb 19:29 Apps</line> <line index="3">drwxr-xr-x 4 root wheel 136 27 Jan 09:14 System</line> <line index="4">drwxrwxr-t 7 root admin 238 16 Aug 16:02 Users</line> <line index="5">drwxrwxrwt 5 root admin 170 12 Feb 23:48 Volumes</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Table 22 describes the elements of a Command Line adapter response.

64

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter responseWindows

Table 22
Element

Elements of a Command Line adapter response (part 1 of 2)

Description Contains the adapter response Contains the request level summary information Specifies the status of the adapter request Valid values: success, error

<command-result> <requestmetadata> <status>

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targets-output> <target-output> <os-id> <os-version> <os-arch>

Contains the output from all the targets Contains the output for a specific target Indicates the operating system type of the target computer Indicates the operating system version of the target computer Indicates the architecture of the target computer This element is absent if the target system does not have a defined architecture.

<target-metadata> Contains the target level summary information

<status>

Indicates the status of the target connection Valid values: success, error

<error>

Specifies the error message returned, if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<commandsoutput> <command-output> <metadata> <command> <working-dir>

Contains the output from all the commands on a single target computer Contains the output from a specific command Contains the command level summary information Contains the command defined in the adapter request Specifies the directory in which the command is executed This element is absent if the attribute is not contained in the request for this command.

<command-dir>

Specifies the directory from which the executed script is to be obtained This element is absent if the attribute did not exist in the request for this command.

<line-count> <executionmilliseconds>

Specifies the number of lines returned in the adapter response Specifies the duration of the command execution, in milliseconds

Chapter 3 Using Terminal adapters

65

Command Line adapter responseWindows

Table 22
Element

Elements of a Command Line adapter response (part 2 of 2)

Description Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a non-zero value. If the exit code is not obtained, a value of 9999 is returned, by default. If the value returned for the <exit-code> is not 0 or 9999, the <status> value is error and an <error> element is present in the response.

<exit-code>

<status>

Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if the <exit-code> returned is not 0 or 9999 When the value of the <status> element is success, this element is absent.

<output> <line>

Contains the output from a single command Specifies the output lines returned by the command The attribute index indicates the sequence in which the line is returned. This can contain any response returned when the <exit-code> is non-zero.

66

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter responseWindows

Figure 51 illustrates a sample adapter response for the Command Line adapter. Figure 51 XML sample of the Command Line adapter response

<command-result> <response-metadata> <status>success</status> <error>Present only with status of 'error'</error> </response-metadata> <targets-output> <target-output> <target-metadata> <os-id>system type</os-id> <os-version>system version</os-version> <os-arch>system architecture</os-arch> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <command>ls -l</command> <working-dir>/</working-dir> <line-count>5</line-count> <execution-milliseconds>169</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <line index="1">total 12617</line> <line index="2">drwxrwxr-x 89 root admin 3026 4 Feb 19:29 Apps</line> <line index="3">drwxr-xr-x 4 root wheel 136 27 Jan 09:14 System</line> <line index="4">drwxrwxr-t 7 root admin 238 16 Aug 16:02 Users</line> <line index="5">drwxrwxrwt 5 root admin 170 12 Feb 23:48 Volumes</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Figure 52 shows a sample adapter request (Windows) for the Command Line adapter to set environment variables. Figure 52 XML sample of the Command Line adapter request to set environment variables Windows

<adapter-request> <env-variables> <env-variable> <name>New_Variable11</name> <value>New_varaible11_value</value> </env-variable> <env-variable> <name>New_Variable22</name> <value>New_varaible22_value</value> </env-variable> </env-variables> <command-request> <commands> <command>dir</command> </commands> </command-request> </adapter-request>

Chapter 3 Using Terminal adapters

67

Command Line adapter responseWindows

Figure 53 shows a sample adapter request (Windows) for the Command Line adapter to clear environment variables. Figure 53 XML sample of the Command Line adapter request to clear environment variables Windows

<adapter-request> <env-variables> <env-variable> <name>New_Variable11</name> <value/> </env-variable> <env-variable> <name>New_Variable22</name> <value/> </env-variable> </env-variables> <command-request> <commands> <command>dir</command> </commands> </command-request> </adapter-request>

68

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter responseWindows

Figure 54 illustrates the sample adapter response (Windows) for the Command Line adapter explaining environment variables. Figure 54 XML sample of the Command Line adapter response explaining environment variables Windows

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows XP</os-id> <os-version>5.1</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ipconfig</command> <line-count>18</line-count> <execution-milliseconds>875</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Windows IP Configuration</line> <line index="2">Ethernet adapter Local Area Connection:</line> <line index="3"> Media State . . . . . . . . . . . : Media disconnected</line> <line index="4">Ethernet adapter Wireless Network Connection:</line> <line index="5"> Connection-specific DNS Suffix . : </line> <line index="6"> IP Address. . . . . . . . . . . . : 192.168.1.2</line> <line index="7"> Subnet Mask . . . . . . . . . . . : 255.255.255.0</line> <line index="18"> Default Gateway . . . . . . . . . : 172.28.0.21</line> </output> </command-output> <command-output> <metadata> <command>set</command> <line-count>44</line-count> <execution-milliseconds>47</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">abc2=abc2</line> <line index="2">ALLUSERSPROFILE=C:\Documents and Settings\All Users</line> <line index="3">APPDATA=C:\Documents and Settings\dbhola\Application Data</line> <line index="4">BAO_INSTALL_HOME=C:\Program Files\ABC Software\AO</line> <line index="5">BMCDEVSTUDIO_HOME=C:\Dev13758\studio</line> . <line index="42">USERPROFILE=C:\Documents and Settings\dbhola</line> <line index="43">VSEDEFLOGDIR=C:\Documents and Settings\All Users\Application Data\McAfee\DesktopProtection</line> <line index="44">windir=C:\WINDOWS</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Chapter 3 Using Terminal adapters

69

Command Line adapter responseWindows

Figure 55 shows a sample adapter request (Windows) for the Command Line adapter using multiple commands. Figure 55 XML sample of the Command Line adapter request using multiple commandsWindows

<windows-commandline-request> <commands <command>ipconfig</command> <command>systeminfo</command> </commands> </windows-commandline-request>

Figure 56 shows a sample adapter response (Windows) for the Command Line adapter using multiple command. Figure 56 XML sample of the Command Line adapter response using multiple commands - Windows (part 1 of 4)

<adapter-response> <execution-duration>23</execution-duration> <status>success</status> <messageBase64></messageBase64> <data> <windows-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="10.128.248.76"> <metadata> <os-id>Windows 2003</os-id> <os-version>5.2 Build 3790 Service Pack 2</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ipconfig</command> <line-count>15</line-count> <execution-milliseconds>5922</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Copyright 2010 ABCD Ltd, Version: 1.1 </line> <line index="2">Connecting to remote service...</line> <line index="3">Connected to remote host.</line> <line index="4">Windows IP Configuration</line> <line index="5">Ethernet adapter Local Area Connection 2:</line> <line index="6"> Connection-specific DNS Suffix . : </line> <line index="7"> Autoconfiguration IP Address. . . : 169.254.240.152</line> <line index="8"> Subnet Mask . . . . . . . . . . . : 255.255.0.0</line> <line index="9"> Default Gateway . . . . . . . . . : </line> <line index="10">Ethernet adapter Local Area Connection:</line> <line index="11"> Connection-specific DNS Suffix . : </line> <line index="12"> IP Address. . . . . . . . . . . . : 10.128.248.76</line> <line index="13"> Subnet Mask . . . . . . . . . . . : 255.255.254.0</line> <line index="14"> Default Gateway . . . . . . . . . : 10.128.248.1</line> <line index="15">Remote application exited with code: 0 </line> </output> </command-output> <command-output>

70

BMC Atrium Orchestrator Base Adapters User Guide

Command Line adapter responseWindows

Figure 56

XML sample of the Command Line adapter response using multiple commands - Windows (part 2 of 4)
<metadata> <command>systeminfo</command> <line-count>285</line-count> <execution-milliseconds>11281</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Copyright 2010 ABC Software Ltd, Version: 1.1 </line> <line index="2">Connecting to remote service...</line> <line index="3">Connected to remote host.</line> <line index="4">Host Name: S-17125</line> <line index="5">OS Name: Microsoft(R) Windows(R) Server 2003, Standard Edition</line> <line index="6">OS Version: 5.2.3790 Service Pack 2 Build 3790</line> <line index="7">OS Manufacturer: Microsoft Corporation</line> <line index="8">OS Configuration: Primary Domain Controller</line> <line index="9">OS Build Type: Multiprocessor Free</line> <line index="10">Registered Owner: Global</line> <line index="11">Registered Organization: ABC</line> <line index="12">Product ID: 69712-641-0555857-45451</line> <line index="13">Original Install Date: 8/30/2007, 8:35:36 PM</line> <line index="14">System Up Time: 1 Days, 14 Hours, 24 Minutes, 4 Seconds</line> <line index="15">System Manufacturer: INTEL_</line> <line index="16">System Model: 04DT044_</line> <line index="17">System Type: X86-based PC</line> <line index="18">Processor(s): 2 Processor(s) Installed.</line> <line index="19"> [01]: x86 Family 15 Model 6 Stepping 4 GenuineIntel ~3391 Mhz</line> <line index="20"> [02]: x86 Family 15 Model 6 Stepping 4 GenuineIntel ~3391 Mhz</line> <line index="21">BIOS Version: INTEL - 49b</line> <line index="22">Windows Directory: C:\WINDOWS</line> <line index="23">System Directory: C:\WINDOWS\system32</line> <line index="24">Boot Device: \Device\HarddiskVolume1</line> <line index="25">System Locale: en-us;English (United States)</line> <line index="26">Input Locale: N/A</line> <line index="27">Time Zone: (GMT+05:30) Chennai, Kolkata, Mumbai, New Delhi</line> <line index="28">Total Physical Memory: 2,046 MB</line> <line index="29">Available Physical Memory: 404 MB</line> <line index="30">Page File: Max Size: 4,945 MB</line> <line index="31">Page File: Available: 1,475 MB</line> <line index="32">Page File: In Use: 3,470 MB</line> <line index="33">Page File Location(s): c:\pagefile.sys</line> <line index="34">Domain: BMCDEV1.com</line> <line index="35">Logon Server: N/A</line> <line index="36">Hotfix(s): 338 Hotfix(s) Installed.</line> <line index="37"> [01]: File 1</line> <line index="38"> [02]: File 1</line>

... <line index="202"> <line index="203"> <line index="204"> <line index="205"> <line index="206"> <line index="207"> <line index="208"> <line index="209"> <line index="210"> Update</line> [166]: [167]: [168]: [169]: [170]: [171]: [172]: [173]: [174]: File 1</line> Q147222</line> KB933854 - QFE</line> KB953298 - QFE</line> SP1 - SP</line> Q936181</line> Q954430</line> Q973688</line> IDNMitigationAPIs -

Chapter 3 Using Terminal adapters

71

Command Line adapter responseWindows

Figure 56

XML sample of the Command Line adapter response using multiple commands - Windows (part 3 of 4)
<line index="211"> [175]: NLSDownlevelMapping Update</line> <line index="212"> [176]: KB925398_WMP64</line> <line index="213"> [177]: KB953838-IE7 Update</line> <line index="214"> [178]: KB956390-IE7 Update</line> <line index="215"> [179]: KB958215-IE7 Update</line> <line index="216"> [180]: KB960714-IE7 Update</line> <line index="217"> [181]: KB961260-IE7 Update</line> <line index="218"> [182]: KB963027-IE7 Update</line> <line index="219"> [183]: KB969897-IE7 Update</line> <line index="220"> [184]: KB972260-IE7 Update</line> <line index="221"> [185]: KB974455-IE7 Update</line> <line index="222"> [186]: KB976325-IE7 Update</line> <line index="223"> [187]: KB976749-IE7 Update</line> <line index="224"> [188]: KB978207-IE7 Update</line> <line index="225"> [189]: KB980182-IE7 Update</line> <line index="226"> [190]: KB914961 - Service Pack</line> <line index="227"> [191]: KB921503 - Update</line> <line index="228"> [192]: KB923561 - Update</line> <line index="229"> [193]: KB924667-v2 Update</line> <line index="230"> [194]: KB925876 - Update</line> <line index="231"> [195]: KB925902 - Update</line> <line index="232"> [196]: KB926122 - Update</line> <line index="233"> [197]: KB927891 - Update</line> <line index="234"> [198]: KB929123 - Update</line> <line index="235"> [199]: KB930178 - Update</line> <line index="236"> [200]: KB931784 - Update</line> <line index="237"> [201]: KB932168 - Update</line> <line index="238"> [202]: KB933360 - Update</line> <line index="239"> [203]: KB933729 - Update</line> <line index="240"> [204]: KB933854 - Update</line> <line index="241"> [205]: KB935839 - Update</line> <line index="242"> [206]: KB935840 - Update</line> <line index="243"> [207]: KB936021 - Update</line> <line index="244"> [208]: KB936357 - Update</line> <line index="245"> [209]: KB936782 - Update</line> <line index="246"> [210]: KB937143 - Update</line> <line index="247"> [211]: KB938127 - Update</line> <line index="248"> [212]: KB938464 - Update</line> <line index="249"> [213]: KB939653 - Update</line> <line index="250"> [214]: KB941202 - Update</line> <line index="251"> [215]: KB941568 - Update</line> <line index="252"> [216]: KB941569 - Update</line> <line index="253"> [217]: KB941644 - Update</line> <line index="254"> [218]: KB941672 - Update</line> <line index="255"> [219]: KB941693 - Update</line>

72

BMC Atrium Orchestrator Base Adapters User Guide

Session-based CLI adapter

Figure 56

XML sample of the Command Line adapter response using multiple commands - Windows (part 4 of 4)
<line index="256"> [220]: KB942763 - Update</line> <line index="257"> [221]: KB942830 - Update</line> <line index="258"> [222]: KB942831 - Update</line> <line index="259"> [223]: KB943055 - Update</line> <line index="260"> [224]: KB943460 - Update</line> <line index="261"> [225]: KB943485 - Update</line> <line index="262"> [226]: KB944653 - Update</line> <line index="263"> [227]: KB945553 - Update</line> <line index="264"> [228]: KB946026 - Update</line> <line index="265"> [229]: KB948496 - Update</line> <line index="266"> [230]: KB948590 - Update</line> <line index="267"> [231]: KB948881 - Update</line> <line index="268"> [232]: KB949014 - Update</line> <line index="269"> [233]: KB950760 - Update</line> <line index="270"> [234]: KB950762 - Update</line> <line index="271"> [235]: KB950974 - Update</line> <line index="272"> [236]: KB951066 - Update</line> <line index="273"> [237]: KB951072-v2 Update</line> <line index="274"> [238]: KB951698 - Update</line> <line index="275"> [239]: KB951746 - U</line> <line index="276">Network Card(s): 2 NIC(s) Installed.</line> <line index="277"> [01]: Intel(R) PRO/1000 MT Network Connection</line> <line index="278"> Connection Name: Local Area Connection</line> <line index="279"> DHCP Enabled: No</line> <line index="280"> IP address(es)</line> <line index="281"> [01]: 10.128.248.76</line> <line index="282"> [02]: Intel(R) PRO/1000 PM Network Connection</line> <line index="283"> Connection Name: Local Area Connection 2</line> <line index="284"> Status: Media disconnected</line> <line index="285">Remote application exited with code: 0 </line> </output> </command-output> </commands-output> </target-output> </targets-output> </windows-command-output> </data> </adapter-response>

Session-based CLI adapter

The Session-based Command Line Interface (CLI) adapter invokes commands that create a sub-shell. The sub-shell provides prompts where you enter commands. The adapter captures the output of the commands that write to the output stream of the process. To use these commands, you must create a request that specifies a prompt and then execute a command that informs the process to read the input/output (I/O) stream until an expected string appears.

Chapter 3 Using Terminal adapters

73

Windows Session-based CLI adapter configuration

The Session-based CLI adapter supports persistent connectivity which means that you can connect multiple requests within a process. The connection lasts until the process ends or the session is disconnected, using the <terminate-on-exit> tag. This functionality is implemented by using the <connection> tag. If the <connection> tag is absent, open a new connection for each subsequent request. For more information, see Persistent connectivity on page 33.

Windows Session-based CLI adapter configuration

In a Windows environment, the Session-based CLI adapter opens a sub-shell. Subsequent commands execute in the sub-shell in a session. You can specify the command at the command level or at the command-group level. The console prompt appears when the system is waiting for a command. This prompt indicates that a command has been executed. Table 23 describes the configuration node elements for the Windows Session-based CLI adapter. Table 23
Element

Configuration node elements of the Windows Session-based CLI adapter

Description Required No

<character-set> Specifies the supporting CharSet CharSet is also called Character set and includes identifiers describing a series of universal characters Default value: ISO-8859-2 <env-variables> Includes more than one environment variable <env-variable> <name> <value> Specifies an environment variable (name-value pair) Specifies the name of the environment variable to be set or cleared Specifies the corresponding value of the environment variable name Note: If the value is empty or not specified, the environment variable is cleared.

No No No No

74

BMC Atrium Orchestrator Base Adapters User Guide

Windows Session-based CLI adapter configuration

Figure 57 shows a sample configuration of the Windows Session-based CLI adapter. Figure 57 XML sample of the Session-based CLI adapter configurationWindows platform

<config> <initial-command> <command prompt="&gt;">cmd.exe</command> </initial-command> <character-set>Shift_JIS</character-set> <prompt>&gt;</prompt> <verify-os>false</verify-os> <env-variables> <env-variable> <name>AddAndThenDelete_Name</name> <value>AddAndThenDelete_Value</value> </env-variable> <env-variable> <name>AddVariable_Name</name> <value>New_AddVariable_Value</value> </env-variable> <env-variable> <name>AddAndThenDelete_Name</name><!-- to delete which is recently added --> <value/> </env-variable> </env-variables> </config>

Figure 58 shows a sample configuration of the Windows Session-based CLI adapter to set environment variables. Figure 58 XML sample of the Session-based CLI adapter configuration to set environment variables

<config/> <env-variables> <env-variable> <name>New_Variable11</name> <value>New_variable11_value</value> </env-variable> <env-variable> <name>New_Variable22</name> <value>New_variable22_value</value> </env-variable> </env-variables> </config>

Figure 59 shows a sample configuration of the Windows Session-based CLI adapter to clear environment variables. Figure 59 XML sample of the Session-based CLI adapter configuration to clear environment variables

<config> <env-variables> <env-variable> <name>New_Variable11</name> <value/> </env-variable> <env-variable> <name>New_Variable22</name> <value/> </env-variable> </env-variables> </config>

Chapter 3 Using Terminal adapters

75

UNIX Session-based CLI adapter configuration

Figure 60 shows a sample configuration of the Windows Session-based CLI with character-set. Figure 60 XML sample of the Session-based CLI configuration with character-set

<config> <initial-command> <command prompt="&gt;">cmd.exe</command> </initial-command> <character-set>Shift_JIS</character-set> </config>

UNIX Session-based CLI adapter configuration

In a UNIX environment, you provide the initial command as a Telnet command, which opens a sub-shell. Subsequent commands execute in the sub-shell in a session. You can specify the command at the command level or at the command-group level. The console prompt appears when the system is waiting for a command. This prompt indicates that a command has been executed. Figure 61 shows a sample configuration of the UNIX Session-based CLI adapter with prompt. Figure 61 XML sample of the Session-based CLI adapter configuration with promptUNIX platform

<config> <initial-command> <command prompt="password:">telnet -l test ao</command> <command prompt="$">test</command> </initial-command> <prompt>$</prompt> </config>

Figure 62 shows a sample configuration of the UNIX Session-based CLI adapter with expect. Figure 62 XML sample of the Session-based Command Line configuration with expectUNIX platform

<config> <initial-command> <command expect="password:">telnet -l test ao</command> <command expect="$">test</command> </initial-command> <expect>$</expect> </config>

76

BMC Atrium Orchestrator Base Adapters User Guide

Session-based CLI adapter requests and responses

Session-based CLI adapter requests and responses

Figure 63 shows the adapter request for the Session-based CLI adapter (Windows).

TIP
The working-dir command works for the first command in the Session-based approach. After the initial command, if the directory changes, you must use the change directory command (cd) to alter the directory location.

Figure 63

XML sample of the Session-based CLI adapter requestWindows

<command-request> <commands> <command working-dirC:\workdir\bmc prompt=&gt; continue-on-failure=false>cd LAP</command> <command prompt="&gt;">cmd.exe</command> <command prompt="&gt;">copy *.cer C:\workdir\bmc</command> <command prompt="Certs&gt;">dir</command> </commands> </command-request>

Figure 64 shows the adapter request for the Session-based CLI adapter for command group (Windows). Figure 64 XML sample of the Session-based CLI adapter request for Command GroupWindows

<command-request> <commands> <command prompt="&gt;">cmd.exe</command> <command-group prompt="&gt;"> <command>cd C:\server123</command> <command>cd C:\logs</command> <command>cd C:\Certs</command> <command>copy *.cer C:\server123</command> <command>dir</command> </command-group> </commands> </command-request>

Chapter 3 Using Terminal adapters

77

Session-based CLI adapter requests and responses

Figure 65 shows the adapter request for the Session-based CLI adapter for persistent connectivity (Windows). Figure 65 XML sample of the Session-based CLI adapter request with persistent connectivity Windows platform

<command-request> <connection> <name>my_named_connection</name> <terminate-on-exit>false</terminate-on-exit> </connection> <commands> <command working-dir"C:\workdir\bmc" prompt="&gt;" continue-onfailure="false">cd LAP</command> <command prompt="&gt;">cmd.exe</command> <command prompt="&gt;">copy *.cer C:\workdir\bmc</command> <command prompt="Certs&gt;">dir</command> </commands> </command-request>

Figure 66 illustrates the adapter response for the Session-based CLI adapter for persistent connectivity (Windows).

78

BMC Atrium Orchestrator Base Adapters User Guide

Session-based CLI adapter requests and responses

Figure 66

XML sample of the Session-based CLI adapter response with persistent connectivity Windows

<command-result> <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>cd C:\\"Documents and Settings"</command> <line-count>0</line-count> <execution-milliseconds>16</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output/> </command-output> <command-output> <metadata> <command>dir </command> <line-count>10</line-count> <execution-milliseconds>78</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1"> Volume in drive C has no label.</line> <line index="2"> Volume Serial Number is D454-12A6</line> <line index="3"> Directory of C:\Program Files\BMC Software\AO7600June3\bin</line> <line index="4">07/08/2009 08:40 PM <DIR> .</line> <line index="5">07/08/2009 08:40 PM <DIR> ..</line> <line index="6">07/08/2009 08:40 PM 115,712 BMC Atrium Orchestrator CDP.exe</line> <line index="7">07/08/2009 08:40 PM 4,031 BMC Atrium Orchestrator CDP.lax</line> <line index="8">07/08/2009 08:40 PM 41,405 lax.jar</line> <line index="9"> 3 File(s) 161,148 bytes</line> <line index="10"> 2 Dir(s) 49,239,662,592 bytes free</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Chapter 3 Using Terminal adapters

79

Session-based CLI adapter requests and responses

Figure 67 shows an adapter request for the Session-based CLI adapter (UNIX). Figure 67 XML sample of the Session-based CLI adapter requestUNIX

<command-request> <commands> <command prompt="password:">telnet -l test</command> <command prompt="$">test</command> <command prompt="$">cd /tmp</command> <command prompt=$>pwd</command> <command prompt=$>ls -la |grep -iv surefire</command> <command prompt="$">cd</command> <command prompt="$">pwd</command> <command ignore-response="true">exit</command> </commands> </command-request>

Figure 68 shows an adapter request for the Session-based CLI adapter for persistent connectivity (UNIX). Figure 68 XML sample of the Session-based CLI adapter request with persistent connectivityUNIX

<command-request> <connection> <name>my_connection</name> <terminate-on-exit>false</terminate-on-exit> </connection> <commands> <command working-dir="/">ls -l</command> <command>pwd</command> </commands> </command-request>

Figure 69 illustrates the adapter response for the Session-based CLI adapter for persistent connectivity (UNIX).

80

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 69

XML sample of the Session-based CLI adapter response with persistent connectivity UNIX platform

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-22.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ls -l</command> <working-dir>/</working-dir> <line-count>24</line-count> <execution-milliseconds>113</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">total 174</line> . . . <line index="24">drwxr-xr-x 25 root root 4096 Aug 19 </output> </command-output> <command-output> <metadata> <command>pwd</command> <line-count>1</line-count> <execution-milliseconds>90</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">/home/user2/CDP7600</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

2008 var</line>

run-as support in Command Line adapter

The run-as feature enables you to execute any program or command using a different user account other than the current logged in user (you). The run-as feature enables you to perform the following tasks:
s s

Switch between different accounts and execute commands or programs Execute any command with elevated or restricted privileges

Chapter 3 Using Terminal adapters

81

run-as support in Command Line adapter

The run-as feature in Command Line adapter is supported on the following platforms: s run-as support on Windows s run-as support on Linux/UNIX s run-as with Kerberos authentication support on Linux/UNIX Support for the run-as feature in the Command Line adapter is platform dependent.

run-as support on Windows

run-as support on Windows enables you to execute any program (.exe) using a different user account other than the currently logged in user (you). To use this feature, set the following attributes:
s s s s

run-as user-name password wait-for-command-output

NOTE
run-as support on Windows does not support execution of DOS commands.

Before you begin

The Command Line adapter uses the PsExec utility to support the run-as feature on Windows platforms. To use the run-as feature on Windows, perform the following steps:

1 Download the PsExec utility that is freely available at

http://technet.microsoft.com/hi-in/sysinternals/bb897553(en-us).aspx.

2 Unbundle the zip file and set the unbundled location to the system's path
environment variable.

3 Restart the grid.

82

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Table 24 describes the adapter request attributes for the Command Line adapter to support the run-as feature on Windows. Table 24
Attribute run-as

Adapter request attributes for the run-as feature in the Command Line adapter Windows
Description Specifies a Boolean value to execute the command as a different user This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) Required No

user-name

Specifies the user name (of an existing user) used to execute the program This attribute is required if you set the run-as attribute to true.

Conditional

password

Specifies the password for the user account specified in the user-name This attribute is required if you set the run-as attribute to true.

Conditional

wait-forcommandoutput

Specifies whether to wait for the process or command output or until the adapter times-out When this value is set to true, the adapter waits for the process output or the adapter time-out duration. When you set this value to false, the adapter returns the execution status of the command. Valid values: true, false (default) Note: BMC recommends that you do not set this attribute to execute programs (.exe) for which no output is expected. For example, notepad.exe.

No

Figure 70 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using simple commands. Figure 70 XML sample of the Command Line adapter request for the run-as feature (Windows) simple commands format

<command-request> <commands> <command run-as="true" user-name="admin" password="admin123" wait-for-commandoutput="true">ipconfig</command> </commands> </command-request>

Figure 72 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using simple commands.

Chapter 3 Using Terminal adapters

83

run-as support in Command Line adapter

Figure 71

XML sample of the Command Line adapter response for the run-as feature (Windows) simple commands format (part 1 of 2)

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows XP</os-id> <os-version>5.1</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ipconfig</command> <line-count>34</line-count> <execution-milliseconds>0</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata><output> <line index="1"></line> <line index="2"></line> <line index="3">Windows IP Configuration</line> <line index="4"></line> <line index="5"></line> <line index="6"></line> <line index="7"></line> <line index="8"></line> <line index="9">Ethernet adapter Local Area Connection:</line> <line index="10"></line> <line index="11"></line> <line index="12"></line> <line index="13"> Connection-specific DNS Suffix . : bmc.com</line> <line index="14"></line> <line index="15"> IP Address. . . . . . . . . . . . : 10.128.249.29</line> <line index="16"></line> <line index="17"> Subnet Mask . . . . . . . . . . . : 255.255.254.0</line> <line index="18"></line> <line index="19"> Default Gateway . . . . . . . . . : 10.128.248.1</line> <line index="20"></line> <line index="21"></line> <line index="22"></line> <line index="23">Ethernet adapter {EDE30461-C964-4723-863BAD7D4CFE4886}:</line> <line index="24"></line> <line index="25"></line> <line index="26"></line> <line index="27"> Connection-specific DNS Suffix . : </line> <line index="28"></line> <line index="29"> IP Address. . . . . . . . . . . . : 0.0.0.0</line> <line index="30"></line> <line index="31"> Subnet Mask . . . . . . . . . . . : 0.0.0.0</line> <line index="32"></line> <line index="33"> Default Gateway . . . . . . . . . : </line> <line index="34"></line> </output> </command-output>

84

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 72

XML sample of the Command Line adapter response for the run-as feature (Windows) simple commands format (part 2 of 2)

</commands-output> </target-output> </targets-output> </command-result>

Figure 73 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using a command group. Figure 73 XML sample of the Command Line adapter request for the run-as feature (Windows) command group format

<command-request> <commands> <command-group> <command run-as="true" user-name="guest2" password="abc123">notepad.exe</command> </command-group> </commands> </command-request>

Figure 74 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using a command group. Figure 74 XML sample of the Command Line adapter response for the run-as feature (Windows) command group format (part 1 of 2)

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows XP</os-id> <os-version>5.1</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>notepad.exe</command> <line-count>24</line-count> <execution-milliseconds>0</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1"></line> <line index="2">PsExec v1.97 - Execute processes remotely</line> <line index="3">Copyright (C) 2001-2009 Mark Russinovich</line> <line index="4">Sysinternals - www.sysinternals.com</line> <line index="5"></line> <line index="6">Access is denied.</line> <line index="7">Connecting to 127.0.0.1...</line> <line index="8"></line> <line index="9"></line> <line index="10">Couldn't access 127.0.0.1:</line>

Chapter 3 Using Terminal adapters

85

run-as support in Command Line adapter

Figure 75

XML sample of the Command Line adapter response for the run-as feature (Windows) command group format (part 2 of 2))

<line index="12"></line> <line index="13"></line> <line index="14">Starting PsExec service on 127.0.0.1...</line> <line index="15"></line> <line index="16"></line> <line index="17">Connecting with PsExec service on 127.0.0.1...</line> <line index="18"></line> <line index="19"></line> <line index="20">Starting notepad on 127.0.0.1...</line> <line index="21"></line> <line index="22"></line> <line index="23"></line> <line index="24">notepad started on 127.0.0.1 with process ID 4912.</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Figure 76 shows a sample adapter request for the Command Line adapter to support the run-as feature on Windows using FAT commands. Figure 76 XML sample of the Command Line adapter request for the run-as feature (Windows) FAT command format

<command-request> <commands> <fat-command> <command os-id="Windows XP"run-as="true" user-name="admin" password="admin123" wait-for-command-output="false">ipconfig</command> </fat-command> </commands> </command-request>

Figure 77 shows a sample adapter response for the Command Line adapter to support the run-as feature on Windows using FAT commands. Figure 77 XML sample of the Command Line adapter response for the run-as feature (Windows) FAT command format (part 1 of 2)

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Windows XP</os-id> <os-version>5.1</os-version> <os-arch>x86</os-arch> <status>success</status> </metadata> <commands-output>

86

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 77

XML sample of the Command Line adapter response for the run-as feature (Windows) FAT command format (part 2 of 2)

<command-output> <metadata> <command>ipconfig</command> <line-count>19</line-count> <execution-milliseconds>0</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1"></line> <line index="2">PsExec v1.97 - Execute processes remotely</line> <line index="3">Copyright (C) 2001-2009 Mark Russinovich</line> <line index="4">Sysinternals - www.sysinternals.com</line> <line index="5"></line> <line index="6">Connecting to 127.0.0.1...</line> <line index="7"></line> <line index="8"></line> <line index="9">Starting PsExec service on 127.0.0.1...</line> <line index="10"></line> <line index="11"></line> <line index="12">Connecting with PsExec service on 127.0.0.1...</line> <line index="13"></line> <line index="14"></line> <line index="15">Starting ipconfig on 127.0.0.1...</line> <line index="16"></line> <line index="17"></line> <line index="18"></line> <line index="19">ipconfig started on 127.0.0.1 with process ID 4812.</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

run-as support on Linux/UNIX

run-as support on Linux/UNIX enables you to execute any program or command using a different user account other than the currently logged in user (you). To use this feature, set the following attributes:
s s s

run-as user-name password

Before you begin

The Command Line adapter uses the sudo command to support the run-as feature. To use the sudo command to support run-as on Linux or UNIX platform, an administrator must add an entry for users with the level of authorization in the /etc/sudoers file.

Chapter 3 Using Terminal adapters

87

run-as support in Command Line adapter

Table 25 describes the adapter request attributes for the Command Line adapter to support the run-as feature on Linux or UNIX. Table 25
Attribute run-as

Adapter request attributes for the run-as feature in the Command Line adapterLinux or UNIX
Description Specifies a Boolean value to execute the command as a different user This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) Required No

user-name

Specifies the user name (of an existing user) used to execute the program This attribute is required if you set the run-as attribute to true.

Conditional

password

Specifies the password of a user who is currently logged on This is the password of a user with which the BMC Atrium Orchestrator service (grid) runs. This attribute is required if you set the run-as attribute to true.

Conditional

Figure 78 shows a sample adapter request for the Command Line adapter to support the run-as feature on Linux or UNIX using simple commands. Figure 78 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)simple commands format

<command-request> <commands> <command run-as="true" user-name="root" password="mypassword">whoami</command> <command run-as="true" user-name="user1" password="mypassword">whoami</command> </commands> </command-request>

Figure 79 shows a sample adapter response for the Command Line adapter to support the run-as feature on Linux or UNIX using simple commands.

88

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 79

XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)simple commands format

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-22.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami</command> <line-count>1</line-count> <execution-milliseconds>68</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">root</line> </output> </command-output> <command-output> <metadata> <command>whoami</command> <line-count>1</line-count> <execution-milliseconds>71</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">user1</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Figure 80 shows a sample adapter request for the Command Line adapter to support the run-as feature on Linux or UNIX using a command group. Figure 80 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)command group format

<command-request> <commands> <command-group> <command run-as="true" user-name="user1" password="mypassword">whoami</command> <command run-as="true" user-name="root" password="mypassword">whoami</command> </command-group> </commands> </command-request>

Figure 81 shows a sample adapter response for the Command Line adapter to support the run-as feature on Linux or UNIX using a command group.

Chapter 3 Using Terminal adapters

89

run-as support in Command Line adapter

Figure 81

XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)command group format

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-22.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami</command> <line-count>1</line-count> <execution-milliseconds>66</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">user1</line> </output> </command-output> <command-output> <metadata> <command>whoami</command> <line-count>1</line-count> <execution-milliseconds>67</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">root</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Figure 82 shows a sample adapter request for the Command Line adapter to support the run-as feature on Linux or UNIX using FAT commands. Figure 82 XML sample of the Command Line adapter request for the run-as feature (Linux or UNIX)FAT command format

<command-request> <commands> <fat-command> <command os-id="Linux"run-as="true" user-name="root" password="mypassword">whoami</command> </fat-command> </commands> </command-request>

Figure 83 shows a sample adapter response for the Command Line adapter to support the run-as feature on Linux or UNIX using FAT commands.

90

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 83

XML sample of the Command Line adapter response for the run-as feature (Linux or UNIX)FAT command format

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-22.ELsmp</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami</command> <line-count>1</line-count> <execution-milliseconds>68</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">root</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

run-as Kerberos authentication support on Linux/UNIX

run-as support with Kerberos authentication on Linux/UNIX enables you to execute any program or command using a different user account other than the currently logged in user (you). The user account is verified using Kerberos authentication mechanism. To use this feature, set the following attributes:
s s s s s

run-as user-name krb-authentication krb-command krb-options

Before you begin

The Command Line adapter uses ksu as the default command to support the run-as feature with Kerberos authentication on Linux or UNIX. ksu is part of Kerberos applications installed with Kerberos V5 (MIT). If you have a different Kerberos authentication mechanism installed on your system that has its own set of Kerberos applications supported (similar to ksu), use the krbcommand and krb-options attributes in the adapter request. Doing this prevents the Command Line adapter from using ksu, the default command.

Chapter 3 Using Terminal adapters

91

run-as support in Command Line adapter

Before executing any command or program using run-as with Kerberos authentication, you must acquire the required Kerberos ticket. If the required Kerberos ticket is not available in the cache, the adapter request fails with a timeout error. Currently, the adapter does not support setting the password for acquiring the required Kerberos ticket.

NOTE
Solaris computers have SEAM Kerberos installed that does not support ksu. You need to first install Kerberos V5 to use the run-as with Kerberos authentication feature on Solaris.

Table 26 describes the adapter request attributes for the Command Line adapter to support the run-as with Kerberos authentication feature on Linux or UNIX. Table 26
Attribute run-as

Adapter request attributes for the run-as with Kerberos authentication feature in the Command Line adapterLinux or UNIX (part 1 of 2)
Description Specifies a Boolean value to execute the command as a different user This attribute must be set to true to execute the command as a different user. Valid values: true, false (default) Required No

user-name

Specifies the name of an existing user using which the program or process is executed This attribute is required if the run-as attribute is set to true.

Conditional

No krbSpecifies a Boolean value to execute the command as a different user authenticat using Kerberos authentication ion This attribute must be set to true to execute the command as a different user using a Kerberos ticket to authenticate the user. Valid values: true, false (default)

92

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Table 26
Attribute

Adapter request attributes for the run-as with Kerberos authentication feature in the Command Line adapterLinux or UNIX (part 2 of 2)
Description Required No

krb-command Specifies the command used by the adapter to support run-as with Kerberos authentication Use this attribute to switch to a different command similar to ksu (for example, kuu). Default value: ksu krb-options Specifies the krb-options for the krb-command Valid values: -n principal_name: Specifies a Kerberos principal name for a specified krb user -c cache_name: Specifies a cache name (for example, FILE:/tmp/my_cache) -k: Specifies that the target cache must not be deleted upon termination of the target shell or a command If you do not specify the -k option, the adapter deletes the target cache. Note: The above command options are specific to ksu. You can set krboptions specific to the krb-command that you specify.

No

Figure 84 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using simple commands. Figure 84 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)simple commands format

<command-request> <commands> <command run-as="true" user-name="krbuser1" krb-authentication="true">whoami</command> <command run-as="true" user-name="krbuser2" krb-authentication="true">whoami</command> </commands> </command-request>

Figure 85 shows a sample adapter response for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using simple commands.

Chapter 3 Using Terminal adapters

93

run-as support in Command Line adapter

Figure 85

XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)simple commands format

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.18-1.2747.el5</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami</command> <line-count>5</line-count> <execution-milliseconds>388</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">krbuser1</line> <line index="2">Authenticated newuser@SYNAPSE.COM</line> <line index="3">Account krbuser1: authorization for newuser@SYNAPSE.COM for execution of</line> <line index="4">/bin/sh successful</line> <line index="5">Changing uid to krbuser1 (508)</line> </output> </command-output> <command-output> <metadata> <command>whoami</command> <line-count>5</line-count> <execution-milliseconds>339</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">krbuser2</line> <line index="2">Authenticated newuser@SYNAPSE.COM</line> <line index="3">Account krbuser2: authorization for newuser@SYNAPSE.COM for execution of</line> <line index="4">/bin/sh successful</line> <line index="5">Changing uid to krbuser2 (509)</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

94

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 86 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using a command group. Figure 86 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)command group format

<command-request> <commands> <command-group> <command run-as="true" user-name="krbuser1" krb-authentication="true">whoami;pwd </command> <command run-as="true" user-name="krbuser2" krb-authentication="true">whoami </command> </command-group> </commands> </command-request>

Figure 87 shows a sample adapter response (Linux) for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using a command group.

Chapter 3 Using Terminal adapters

95

run-as support in Command Line adapter

Figure 87

XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)command group format (part 1 of 2)

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.18-1.2747.el5</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami;pwd</command> <line-count>6</line-count> <execution-milliseconds>396</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">krbuser1</line> <line index="2">/home/newuser/CDP_750207</line> <line index="3">Authenticated newuser@SYNAPSE.COM</line> <line index="4">Account krbuser1: authorization for newuser@SYNAPSE.COM for execution of</line> <line index="5">/bin/sh successful</line> <line index="6">Changing uid to krbuser1 (508)</line> </output> </command-output> <command-output> <metadata>

96

BMC Atrium Orchestrator Base Adapters User Guide

run-as support in Command Line adapter

Figure 87

XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)command group format (part 2 of 2)

<command>whoami</command> <line-count>5</line-count> <execution-milliseconds>520</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">krbuser2</line> <line index="2">Authenticated newuser@SYNAPSE.COM</line> <line index="3">Account krbuser2: authorization for newuser@SYNAPSE.COM for execution of</line> <line index="4">/bin/sh successful</line> <line index="5">Changing uid to krbuser2 (509)</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

Figure 88 shows a sample adapter request for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using FAT commands. Figure 88 XML sample of the Command Line adapter request using run-as feature with Kerberos authentication (Linux or UNIX)FAT command format

<command-request> <commands> <fat-command> <command os-id="Linux"run-as="true" user-name="krbuser1" krb-authentication="true"> whoami</command> </fat-command> </commands> </command-request>

Figure 89 shows a sample adapter response for the Command Line adapter to support the run-as feature with Kerberos authentication on Linux or UNIX using FAT commands.

Chapter 3 Using Terminal adapters

97

SSH adapter

Figure 89

XML sample of the Command Line adapter response using run-as feature with Kerberos authentication (Linux or UNIX)FAT command format

<command-result> <metadata> <status>success</status> </metadata> <targets-output> <target-output> <metadata> <os-id>Linux</os-id> <os-version>2.6.18-1.2747.el5</os-version> <os-arch>i386</os-arch> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>whoami</command> <line-count>5</line-count> <execution-milliseconds>462</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">krbuser1</line> <line index="2">Authenticated newuser@SYNAPSE.COM</line> <line index="3">Account krbuser1: authorization for newuser@SYNAPSE.COM for execution of</line> <line index="4">/bin/sh successful</line> <line index="5">Changing uid to krbuser1 (508)</line> </output> </command-output> </commands-output> </target-output> </targets-output> </command-result>

SSH adapter
The SSH adapter is used to execute commands on a remote host using the SSH protocol. With this adapter, the use of a prompt is optional. If a <prompt> element is not defined, each command is executed in a separate session, as if each command is executed in a new command shell. Each command is executed independently, without any effect on subsequent commands. With the definition of a <prompt> element, commands are executed in a sequence, in the same login shell. Executing a command with non-prompt-based SSH is similar to appending the command to a Linux or Solaris client's command (ssh user1@server1 ls). This results in an environment that is different from prompt-based SSH, in which the command is executed within the context of a login shell. The SSH adapter can use the common features described inTerminal adapter features on page 23.

98

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter configuration

SSH adapter configuration

For the SSH adapter, in addition to target computers defined in the adapter configuration, you can define dynamic target computers in each adapter request. If a dynamic target is defined in the SSH adapter request, use a configuration node, <config/>, in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-ssh[version] Default adapter name: SSHAdapter To configure the SSH adapter, see Configuring the adapter on page 14. Table 27 describes the adapter configuration elements for the SSH adapter that you can specify by 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. Table 27
UI label Target Port

Configuration node elements of the SSH adapter (part 1 of 4)

Element <target> <port> Description Specifies the host name or the IP address of the remote host computer Specifies the port on which the remote host listens Default value: 22 Required Yes No

User Name Password

<user-name> <password>

Specifies the user name required for remote host authentication Specifies the password corresponding to the specified user name If this value is not defined, the <private-key-file> element can be used. This element can contain a encryption-type attribute to indicate that the specified password is encrypted. Valid values: Base64, Plain (non-encrypted) (default)

Yes No

Note: If you provide the <password> and <private-key-file> elements in the Grid Configuration, the <private-key-file> approach is used and the <password> element is ignored.

Chapter 3 Using Terminal adapters

99

SSH adapter configuration

Table 27
UI label

Configuration node elements of the SSH adapter (part 2 of 4)

Element <privatekey-file> Description Identifies the path and file name of the local SSH key file This file is used for public key authentication. The path and file must exist on the peer servicing the adapter request. This element is used if the <password> element is not provided. Note: If you provide the <password> and <private-key-file> elements in the Grid Configuration, the <private-key-file> approach is used and the <password> element is ignored. Required Conditional

Private Key File

Pass Phrase

<passphrase>

Identifies the pass phrase that protects the private key file This element might be used if the <password> element is not provided. This element can contain a encryption-type attribute to indicate whether the passphrase provided is encrypted. Valid values (encryption type): Base64, Plain (unencrypted) (default)

Conditional

Prompt

<prompt>

Specifies the console prompt displayed when the system is waiting for a command (the terminating string, typically ending with $, >, or # ) The <prompt> element is required to use the proxy command feature. Each command executes in a separate session, as if each command is executing in a new command shell. This prompt indicates the completion of the command execution. It must be unique, not matching the potential command output to prevent parsing issues.

Conditional

100

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter configuration

Table 27
UI label

Configuration node elements of the SSH adapter (part 3 of 4)

Element <timeoutsecs> Description Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. You need this element even if you specify the <establish-connection-timeout-secs> element defined in the target block or the <timeout-secs> element defined in the command block. This element is used for the echo $? commands to pick up the exit code of the commands, and is also used as the timeout for all the commands run to determine the kind of operating system to which the adapter is connected. This element is not used when connecting to or disconnecting from the adapter. Default value: 60 seconds Required No

Timeout Secs

Known Hosts <knownConfig hostsconfig>

Identifies the path to the local known_hosts file This file is used to perform key verification. Default value: home_dir/.ssh/known_hosts

No

Allow Unknown Hosts

<allowunknownhosts>

Determines whether a connection must continue if the key verification fails Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.

No

Preferred Pk Algorithm

<preferredpkalgorithm>

Specifies the preference of the algorithm used to encrypt the public key Valid values: ssh-dss, ssh-rsa (default)

No

Chapter 3

Using Terminal adapters

101

SSH adapter configuration

Table 27
UI label

Configuration node elements of the SSH adapter (part 4 of 4)

Element <establishconnectiontimeoutsecs> Description Required Specifies the time, in seconds, that the adapter waits for No user authentication on the target server If authentication is not successful within the specified time, an error message is returned. Even if the adapter is busy, if a command takes longer than this time to finish and returns no progress messages or any input of any type for longer than the <establish-connection-timeout-secs>, the adapter disconnects. The adapter disconnects after <establish-connection-timeout-secs> even if you specify the <timeout-secs> to be longer. For example, if <establish-connectiontimeout-secs> is 60 seconds, and <timeout-secs> is 1800 seconds, but the command returns nothing while it runs, the adapter times out at 60 seconds. However, if the command returns some progress indication (messages of each step it does, dots, and so on), the adapter does not disconnect until 1800 seconds. Default value: 60 seconds

Establish Connection Timeout Secs

Network Environment

<networkCreates an extra channel session for use with Sun environment> Solaris 9 Valid values: true, false (default) Note: The value must be false when connecting to network devices.

No

Line Termination

<lineSpecifies the line termination character used with the termination> SSH command Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;). Default value: No line termination character is assigned

No

Character Set

<characterset>

Specifies the supporting CharSet CharSet is also called Character set and includes identifiers describing a series of universal characters. Default value: ISO-8859-2

No

Figure 90 on page 103 and Figure 91 on page 103 show the XML templates for SSH adapter configurations.

102

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter configuration

Figure 90

XML template of the SSH adapter configurationpassword approach

<config> <config name = ""> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <prompt></prompt> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <line-termination></line-termination> </config>

Figure 91

XML template of the SSH adapter configurationprivate-key-file approach

<config> <config name = ""> <target></target> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type = ""></pass-phrase> <prompt></prompt> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <line-termination></line-termination> </config>

NOTE
BMC recommends that you use the password or the private-key-file approach; not both the approaches together.

Figure 92 shows an XML sample for SSH adapter configuration with CharSet. Figure 92 XML sample of the SSH adapter configuration with CharSet

<config name="KbiConfig"> <target>server1</target> <user-name>testuser</user-name> <port>22</port> <password>abc</password> <allow-unknown-hosts>true</allow-unknown-hosts> <character-set>Shift_JIS</character-set> </config>

Chapter 3

Using Terminal adapters

103

SSH adapter request

SSH adapter request

The SSH adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. To configure an adapter request for communicating with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. If a <targets> block is not provided, the default target from the adapter configuration is used. When the adapter request is formed using the Advanced Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they elements might cause errors. Table 28 describes the adapter request elements for the SSH adapter. Table 28
Element <prompts>

Adapter request elementsSSH adapter (part 1 of 5)

Description Contains any additional <prompt> elements that might be needed to execute the commands properly The <prompts> element is required when one or more <prompt> elements are defined. Required Conditional

<prompt>

Specifies the console prompt displayed when the system is waiting for a command The name attribute of this element is used to specify the <prompt> value in a <command> element. If not provided, the <prompt> defined in the configuration node or the dynamic target computer is used.

No

Note: This <prompt> indicates the completion of the command execution. It must be unique, not matching potential command output to prevent parsing issues. <targets> Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Contains a name attribute referencing a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used. Conditional Conditional

104

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter request

Table 28
Element <host>

Adapter request elementsSSH adapter (part 2 of 5)

Description Specifies the host name or the IP address of the remote host This element applies to a dynamic target computer and is required when defining a dynamic target. Required Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target. Default value: 22

Conditional

<user-name>

Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target.

Conditional

<password>

Specifies the password corresponding to the <user-name> provided This element contains a password-encryption attribute that indicates whether the specified password is encrypted. Valid values: Base64 or Plain Default value: Plain (non-encrypted)

No

<use-psuedo terminal>

Enables the use of pseudo terminals when invoking SSH connections This element can only be used when the requests or connections do not contain any prompt elements Default value: true

Conditional

<privatekey-file>

Identifies the path and the file name for the local SSH key file This file is used when performing public key authentication. This element can be used if <password> is not provided. The path and file must exist on the peer servicing the adapter request.

Conditional

<passphrase>

Identifies the passphrase used to protect the private key file This element might be used if <password> is not provided. This element can contain an attribute of encryption-type to indicate whether the passphrase provided is encrypted. Valid values (encryption type): Base64, Plain (unencrypted) (default)

Conditional

<prompt>

Specifies the console prompt displayed when the system is waiting for a command This element applies to a dynamic target. It is required when using the proxy command feature. If this element is not supplied, each command executes in a separate session, as if the command is executed in a new command shell. This prompt indicates the completion of the command execution. It must be unique, not matching potential command output to prevent parsing issues.

Conditional

Chapter 3

Using Terminal adapters

105

SSH adapter request

Table 28
Element

Adapter request elementsSSH adapter (part 3 of 5)

Description Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. You need this element even if you have specified the <establishconnection-timeout-secs> element defined in the target block or the <timeout-secs> element defined in the command block. This element is used for the echo $? commands to pick up the exit code of the commands, and is also used as the timeout for all the commands run to determine the kind of operating system to which the adapter is connected. This element is not used when connecting to or disconnecting from the adapter. Default value: 60 seconds Required Conditional

<timeoutsec>

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used to perform key verification. This element applies to a dynamic target. Default value: home_dir /.ssh/known_hosts

Conditional

<allowunknownhosts>

Determines whether a connection must continue if the key verification fails Conditional Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.

<preferredpkalgorithm>

Specifies the preference of the algorithm used to encrypt the public key This element applies to a dynamic target. Valid values: ssh-dss, ssh-rsa (default)

Conditional

106

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter request

Table 28
Element

Adapter request elementsSSH adapter (part 4 of 5)

Description Required Specifies the time, in seconds, that the adapter waits for user authentication No on the target server If authentication is not successful within the specified time, an error message is returned. Even if the adapter is busy, if a command takes longer than this time to finish and returns no progress messages or any input of any type for longer than the <establish-connection-timeout-secs>, the adapter disconnects. The adapter disconnects after <establish-connectiontimeout-secs> even if you specify the <timeout-secs> to be longer. For example, if <establish-connection-timeout-secs> is 60 seconds, and <timeout-secs> is 1800 seconds, but the command returns nothing while it runs, the adapter times out at 60 seconds. However, if the command returns some progress indication (messages of each step it does, dots, and so on), the adapter does not disconnect until 1800 seconds. Default value: 60 seconds

<establishconnectiontimeoutsecs>

<networkCreates an extra channel session for use with Sun Solaris 9. This value must No environment> be false when connecting to network devices. Valid values: true, false (default) <lineSpecifies the line termination character used when invoking the SSH termination> command Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;) Default value: No line termination character is assigned <commands> Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. No No

Chapter 3

Using Terminal adapters

107

SSH adapter request

Table 28
Element

Adapter request elementsSSH adapter (part 5 of 5)

Description Specifies a string that has the commands and arguments for the request Parameters other than the <command> type may be provided when using the wrapper parameters like <target> or <prompts>. The default command is echo Success. If only the <command> parameter is present, the workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> If only the <commands> parameter is present, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands> If both, <command> and <commands> are present, the workflow executes the command provided by the user. Note: If you specify a value for <timeout-sec> in the <command> block, this value is used. Else, the value for <timeout-sec> in the target block is used. For example, if you specify <command timeout-secs="120"> in the <command> block, and <timeout-sec></timeout-sec> in the target block, the command times out after 120 seconds. Required No

<command>

<connection- Allows to change the prompt every time a connection is established, by initialize- running a command to change the prompt as the first command after the command> session is opened This element is supported only in case of named connection (persistent connectivity) You can specify any command within this tag which will get executed while initializing the connection. <characterset> Specifies the supporting CharSet CharSet is also called Character set that includes identifiers describing a series of universal characters. 108 BMC Atrium Orchestrator Base Adapters User Guide

No

No

SSH adapter request

Figure 93 shows a sample XML template for the SSH adapter request. Figure 93 XML template of the SSH adapter request

<ssh-request> <prompts> <prompt name =""></prompt> </prompts> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password encryption-type=""></password> <prompt></prompt> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <line-termination></line-termination> </target> <target> <host></host> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type=""></pass-phrase> <prompt></prompt> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <line-termination></line-termination> </target> </targets> <commands> <command prompt=""></command> <command timeout-secs=""></command> <command></command> </commands> </ssh-request>

Figure 94 shows an XML sample for the SSH adapter request using the <usepseudo-terminal> command. Figure 94 XML sample of the SSH adapter request with use-pseudo-terminal command

<ssh-request> <targets> <target> <host>server1</host> <port>22</port> <user-name>user</user-name> <password>abc</password> <use-pseudo-terminal>true</use-pseudo-terminal> </target> </targets> <commands> <command>type testFile.txt</command> </commands> </ssh-request>

Chapter 3

Using Terminal adapters

109

SSH adapter request

Figure 95 shows an XML sample for the SSH adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 95 XML sample of the SSH adapter request

<ssh-request> <targets> <target> <host>10.128.248.97</host> <user-name>user-name1</user-name> <password>password for user-name1</password> <allow-unknown-hosts>true</allow-unknown-hosts> <prompt>#</prompt> <port>22</port> <connection> <name>sshtarget_connection</name> <terminate-on-exit>false</terminate-on-exit> <connection-initialize-commands> <command prompt="MYPROMPT $">export PS1="MYPROMPT $"</command> <command prompt="MYPROMPT $">pwd</command> <command prompt="MYPROMPT $">cd Desktop</command> </connection-initialize-commands> </connection> </target> </targets> <prompts> <prompt name="first">login:</prompt> <prompt name="second">root@10.128.248.106's password:</prompt> <prompt name="third">#</prompt> </prompts> <commands> <command>hostname</command> <command prompt="second" ignore-exit-code="true">ssh root@10.128.248.106</command> <command prompt="third" ignore-exit-code="true">root@123</command> <command prompt="third" ignore-exit-code="true">ls</command> </commands> </ssh-request>

Figure 96 shows an XML sample of the SSH adapter with CharSet. Figure 96 XML sample of the SSH adapter request with CharSet

<ssh-request> <targets> <target> <host>server1</host> <port>22</port> <user-name>user</user-name> <password>abc</password> <allow-unknown-hosts>true</allow-unknown-hosts> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <command>type testFile.txt</command> </commands> </ssh-request>

110

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter response

SSH adapter response

The SSH adapter returns an adapter response that contains the details for the command executed by the adapter request. Table 29 describes the elements of an SSH adapter response. Table 29
Element <requestmetadata> <status>

Elements of an SSH adapter response (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned if the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targets-output> <target-output>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target.

<target-metadata> Contains the target level summary information <os-id> <os-version> <os-arch> Indicates the operating system type of the target Indicates the operating system version of the target Indicates the architecture of the target system This is absent if the target system does not have a defined architecture. <status Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commands-output> Contains the command responses for all the commands executed on the target computer <command-output> <metadata> <command> <line-count> <executionmilliseconds> Contains the command response for a specific command Contains the command summary information Specifies the command executed Specifies the number of lines returned by the command Specifies the duration of the command execution, in milliseconds

Chapter 3

Using Terminal adapters

111

SSH adapter response

Table 29
Element

Elements of an SSH adapter response (part 2 of 2)

Description Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. If the value returned for the <exit-code> is not 0 or 9999, the value of the <status> element is error, and an <error> element is present in the response.

<exit-code>

<status>

Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output> <line>

Contains any lines that result from the command Specifies the output resulting from the command The index attribute indicates the sequence in which the line is returned. This can contain any response returned when the <exit-code> is nonzero.

112

BMC Atrium Orchestrator Base Adapters User Guide

SSH adapter response

Figure 97 shows the adapter response for the SSH adapter. Figure 97 XML sample of the SSH adapter response (part 1 of 2)

<ssh-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="10.128.248.97"> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-42.ELsmp</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>hostname</command> <line-count>2</line-count> <execution-milliseconds>16</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">realops-linux.abc.com</line> <line index="2">[root@realops-linux ~]#</line> </output> </command-output> <command-output> <metadata> <command>ssh root@10.128.248.106</command> <line-count>1</line-count> <execution-milliseconds>297</execution-milliseconds> <exit-code>9999</exit-code> <status>success</status> </metadata> <output> <line index="1">root@10.128.248.106's password:</line> </output> </command-output> <command-output> <metadata> <command>root@123</command> <line-count>3</line-count> <execution-milliseconds>22062</execution-milliseconds> <exit-code>9999</exit-code> <status>success</status> </metadata> <output> <line index="1">Last login: Tue Apr 20 12:35:32 2010 from 10.128.248.86</line> <line index="2">-bash: REPO: command not found</line> <line index="3">[root@realops-sshclient ~]#</line> </output> </command-output> <command-output> <metadata> <command>ls</command> <line-count>16</line-count> <execution-milliseconds>172</execution-milliseconds> <exit-code>9999</exit-code> <status>success</status> </metadata> <output>

Chapter 3

Using Terminal adapters

113

SSH adapter keyboard-interactive capabilities

Figure 97

XML sample of the SSH adapter response (part 2 of 2)

<line index="1">[00m[00manaconda-ks.cfg[00m [00mprofile413456623[00m</line> <line index="2">[01;34mDesktop[00m [00mprofile425614260[00m</line> <line index="3">[00minstall.log[00m [00mprofile615033302[00m</line> <line index="4">[00minstall.log.syslog[00m [01;31mtelnet-server0.17-26.EL3.3.i386.rpm[00m</line> <line index="5">[01;34mjava[00m [01;31mvsftpd-2.0.18.el4.i386.rpm[00m</line> <line index="6">[01;32mjdk-6u16-solaris-i586.sh[00m [00mzprofile1104250438[00m</line> <line index="7">[01;32mjdk-6u16-solaris-sparc.sh[00m [00mzprofile1429689734[00m</line> <line index="8">[01;32mjdk-6u16-solaris-sparcv9.sh[00m [00mzprofile1632425172[00m</line> <line index="9">[00mprofile1064777096[00m [00mzprofile1760702416[00m</line> <line index="10">[00mprofile1178790592[00m [00mzprofile1877235460[00m</line> <line index="11">[00mprofile1379315196[00m [00mzprofile2053475337[00m</line> <line index="12">[00mprofile1647775163[00m [00mzprofile437787547[00m</line> <line index="13">[00mprofile1835270538[00m [00mzprofile478856458[00m</line> <line index="14">[00mprofile2042636870[00m [00mzprofile667791972[00m</line> <line index="15">[00mprofile2068878841[00m [00mzprofile861707713[00m</line> <line index="16">[m[root@realops-sshclient ~]#</line> </output> </command-output> </commands-output> </target-output> </targets-output> </ssh-command-output>

SSH adapter keyboard-interactive capabilities

Keyboard-interactive (KBI) authentication is a form of authentication for SSH that mimics the process of keyboard interaction, sending authentication information in the SSH servers request. SSH KBI adapter uses user name and password information for authentication. The authentication involves the server sending prompts to the client, which must respond correctly. When the server sends the list of prompts that require responses, the client searches for each prompt in the list of loaded prompts, looking in the request file or the configuration file. The client then sends the set of responses back to the server. If the expected responses are supplied, the authentication succeeds. The following steps must be followed before configuring the adapter to configure the host to support KBI as an authentication method.

114

BMC Atrium Orchestrator Base Adapters User Guide

SSH KBI adapter configuration

To configure the host to allow SSH KBI adapter 1 Edit the /etc/ssh/sshd_config server configuration file. A Change the KbdInteractiveAuthentication parameter to yes.
KbdInteractiveAuthentication specifies whether to allow authentication using the KBI authentication method. You must set the value of this parameter to yes.

B (optional) Change the ChallengeResponseAuthentication attribute to yes.

On some systems, setting ChallengeResponseAuthentication to yes enables the KBI authentication method on the host.

2 Restart sshd service on the host using the service sshd restart command.

SSH KBI adapter configuration

Refer for Table 27 on page 99 for the configuration elements of the SSH KBI adapter. The SSH adapter supports KBI authentication. Figure 98 provides a sample SSH KBI adapter configuration. Figure 98 XML sample of the SSH adapter configuration with KBI

<config name="dev1"> <target>host1</target> <port>xx</port> <userName>user1</userName>

<allow-unknown-hosts>false</allow-unknown-hosts> <private-key-file>${SOME_LOCATION}/.ssh/id_dsa</private-key-file>
</config>

SSH KBI adapter request

Figure 99 shows the adapter request for the SSH KBI adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 3

Using Terminal adapters

115

SSH KBI adapter response

Figure 99

XML sample of the SSH KBI adapter request

<ssh-request> <targets> <target name="T1"> <host>sever6-rds33</host> <port>22</port> <user-name>user</user-name> <password>test</password> <prompt>#</prompt> <allow-unknown-hosts>true</allow-unknown-hosts>

</target>
</targets> <commands> <command >ls</command> </commands> </ssh-request>

SSH KBI adapter response

Figure 100 illustrates the adapter response for the SSH KBI adapter. Figure 100 XML sample of the SSH KBI adapter response
<ssh-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="vm-rhel4asu6-rds33"> <metadata> <os-id>Linux</os-id> <os-version>2.6.9-67.ELsmp</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ls</command> <line-count>2</line-count> <execution-milliseconds>63</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">\[00m\[00manaconda-ks.cfg\[00m \[00minstall.log\[00m \[00minstall.log.syslog\[00m</line> <line index="2">\[m[root@vm-rhel4asu6-rds33 ~]\#</line> </output> </command-output> </commands-output> </target-output> </targets-output> </ssh-command-output>

116

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter

Kerberized SSH adapter

The Kerberized SSH adapter uses Kerberos to securely authenticate clients prior to executing SSH commands on a remote host. This adapter supports the following client types for Kerberos authentication:
s

Java client: This adapter type is used when the target SSH server supports GSS-API-based Kerberos authentication for the SSH2 protocol. The LoginModule within the Sun Java Authentication and Authorization Services (JAAS) is used to authenticate and obtain a Kerberos ticket. SSH2 is the only supported protocol for this type. Local client: This adapter type invokes the SSH client executable and makes use of what ever is available on that local host and matching the SSH server implementation. This client type uses the sun.security.krb5.internal. tools.Kinit Sun class to obtain the Kerberos ticket before invoking the SSH client. This client type supports both SSH1 and SSH2 protocols, provided both the local SSH client and the target SSH server are compatible. The SSH server must allow creation of pseudo terminal client sessions to use a prompt while issuing commands.

With either client type implementation for this adapter, the use of a prompt is optional. If a <prompt> element is not defined, each command is executed in a separate session, as if each was executed in a new command shell. Each command is executed independently, without effect on subsequent commands. With the definition of a <prompt>, commands are executed in a sequence, in the same login shell. Executing a command with non-prompt-based SSH is analogous to appending the command to a Linux or Solaris client's command (ssh user1@server1 ls). This results in an environment that is different from prompt-based SSH, in which the command is executed within the context of a login shell.

Chapter 3

Using Terminal adapters

117

Kerberized SSH adapter

Both types of Kerberized SSH adapters can use can use the following common features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s s

s s s s s

Multiple Configuration nodes Dynamic Targets FAT CommandsCommand attributes: encryption-type timeout-secs continue-on-failure disable-line-termination is-special-character ignore-exit-code ignore-response os-id os-version Password attribute: encryption-type Verification of OS Persistent Connectivity: This feature is available only for Kerberized SSH2 adapter. Proxy Commands: This feature is available only when a <prompt> is defined. Verification of OS

This section describes the following configurations and features of the Kerberized SSH adapters:
Available actions Kerberized SSH adapter (Java client)adapter configuration Kerberized SSH adapter (local client)adapter configuration Kerberized SSH adapter (Java client)adapter response Kerberized SSH adapter (Java client)adapter request Kerberized SSH adapter (local client)adapter request Kerberized SSH adapter (local client)adapter response

118

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (Java client)adapter configuration

Kerberized SSH adapter (Java client)adapter configuration

In addition to targets defined in the adapter configuration, the Kerberized SSH adapter can have dynamic targets defined in each adapter request. If a dynamic target is always defined in the Kerberized SSH adapter request, <config/> configuration node can be used in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-kerberos-ssh2[version] Default adapter name: KerberosSSH2Adapter To configure the Kerberized SSH adapter, see Configuring the adapter on page 14. Table 30 describes the adapter configuration elements for the Kerberized SSH adapter that you can specify by 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. Table 30
UI label

Configuration node elementsKerberized SSH adapter (part 1 of 3)

Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

Target Port

<target> <port>

Specifies the host name or the IP address of the remote host Specifies the port on which the remote host listens Default value: 22

Yes No

User Name Password

<user-name> <password>

Specifies the name of the user registered as the Kerberos user principal Specifies the password that corresponds to the <user-name> provided This element can contain a encryption-type attribute to indicate whether the password provided is encrypted. Valid values: Base64, Plain (non-encrypted) (default)

Conditional Conditional

Krb Realm

<krb-realm>

Specifies the name of the Kerberos realm

Conditional

Chapter 3

Using Terminal adapters

119

Kerberized SSH adapter (Java client)adapter configuration

Table 30
UI label Kdc Name

Configuration node elementsKerberized SSH adapter (part 2 of 3)

Element <kdc-name> Description Specifies the name of the host acting as the Key Distribution Center (KDC) If the host name provided is not a Fully Qualified Domain Name (FQDN), this shortened host name, and not the FQDN, must exist in the Kerberos database. Required Conditional

Use Subject Credentials

<useUses credentials available inside the Java subjectAuthentication and Authorization Service (JAAS) credentials> authenticated Subject instance Valid values: true (default), false With a value of false, Kinit (used to obtain and cache Kerberos ticket-granting ticket) is used to acquire initial credentials. This value is typically set to true in production environments.

No

Krb Login Config File

<krb5-login- Specifies the path and file name of the login properties No config-file> file Default value: blank

Krb5 Debug

No <krb5-debug> Enables debug level logging for Kerberos related supporting logic in SUN Java language for this feature Valid values: true, false (default)

Prompt

<prompt>

Specifies the console prompt displayed when the system is waiting for a command The <prompt> element is required when using the proxy command feature. If not provided, each command executes in a separate session, as if each command is executing in a new command shell. This prompt indicates the completion of the command execution. It must be unique, not matching potential command output to prevent parsing issues.

Conditional

Timeout Secs

<timeoutsecs>

Specifies the time, in seconds, to wait for the expected No prompt to be returned If the expected prompt is not returned within the specified time, an error message returns. Default value: 60 seconds

120

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (Java client)adapter configuration

Table 30
UI label

Configuration node elementsKerberized SSH adapter (part 3 of 3)

Element <establishconnectiontimeoutsecs> Description Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned. Default value: 60 seconds Required No

Establish Connection Timeout Secs

Network Environment

<networkCreates an extra session for use in Sun Solaris 9 environment> environments Valid values: true, false (default) This value must be set to false when establishing a connection to a network appliance.

No

Line Termination

<lineSpecifies the line termination character that is used termination> when invoking the SSH command Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;). Default value: No line termination character is assigned

No

Figure 101 shows an XML template of the adapter configuration for the Kerberized SSH adapter with a Java client. Figure 101 XML template of the Kerberized SSH adapter (Java client) configuration
<config name=""> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <krb-realm></krb-realm> <kdc-name></kdc-name> <use-subject-credentials></use-subject-credentials> <krb5-login-config-file></krb5-login-config-file> <krb5-debug></krb5-debug> <prompt></prompt> <timeout-secs></timeout-secs> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <line-termination>&#013;</line-termination> </config>

Chapter 3

Using Terminal adapters

121

Kerberized SSH adapter (Java client)adapter request

Kerberized SSH adapter (Java client)adapter request

The Kerberized SSH adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. Partial information cannot be retrieved from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, the template must be enclosed within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 31 describes the adapter request elements for the Kerberized SSH adapter. Table 31
Element <prompts>

Adapter request elements of the Kerberized SSH adapter Java client (part 1 of 3)
Description Contains additional <prompt> elements needed to execute the commands properly The <prompts> element is required when one or more <prompt> elements are defined. Required Conditional

<prompt>

Displays the console prompt when the system is waiting for a command A name attribute is used to specify the <prompt> value in a <command> element. In the absence of a value for this element, the <prompt> defined in the configuration node or the dynamic target is used.

No

Note: The prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. <targets> Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. Default value: Default target in the adapter configuration Conditional Conditional

122

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (Java client)adapter request

Table 31
Element <host>

Adapter request elements of the Kerberized SSH adapter Java client (part 2 of 3)
Description Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required when defining a dynamic target. Required Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target. Default value: 22

No

<user-name>

Specifies the name of the user registered as the Kerberos user principal Conditional This element applies to a dynamic target and is required when defining a dynamic target.

<password>

Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target and is required when defining a dynamic target.

Conditional

Note: This element can contain a password-encryption attribute to indicate whether the password provided is encrypted. Valid values: Base64, Plain (non-encrypted) (default) <krb-realm> Specifies the name of the Kerberos realm (set of Kerberos principals) This element applies to a dynamic target and is required when defining a dynamic target. <kdc-name> Specifies the name of the host acting as the Key Distribution Center (KDC) This element applies to a dynamic target and is required when defining a dynamic target. Note: If the host name provided is not a Fully Qualified Domain Name (FQDN), this shortened host name, not the FQDN, must exist in the Kerberos database. <use-subjectcredentials> Uses credentials available inside the JAAS authenticated Subject instance Valid values: true (default), false Note: With a value of false, Kinit is used to acquire initial credentials. This value is typically set to true in production environments. <krb5-loginconfig-file> <krb5-debug> Specifies the path and file name of the login properties file Default value: krb5login.properties file in the classpath Enables debug level logging for Kerberos Valid values: true, false (default) No No No Conditional Conditional

Chapter 3

Using Terminal adapters

123

Kerberized SSH adapter (Java client)adapter request

Table 31
Element <prompt>

Adapter request elements of the Kerberized SSH adapter Java client (part 3 of 3)
Description Displays the console prompt when the system is waiting for a command This element applies to a dynamic target and is required when using the proxy command feature. If not provided, each command is executed in a separate session, as if each command is executed in a new command shell. This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. Required Conditional

<timeout-secs>

Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. This element applies to a dynamic target. Default value: 60 seconds

No

<establishconnectiontimeout-secs>

Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned. Default value: 60 seconds

No

<networkenvironment>

Create an extra session for use in Sun Solaris 9 environments Valid values: true, false (default) This value must be set to false when establishing a connection to a network appliance.

No

<linetermination>

Specifies the line termination character that is used when invoking the No SSH command Typically, the value is a hexadecimal value for \r (&# D;) or \n (&# A;). Default value: No line termination character is assigned

<commands> <command>

Contains the <command> elements Specifies the command to be executed on the remote host The command must be entered as if it were being keyed at the system prompt. A line-termination attribute can be used to provide a command-specific line termination character. This takes precedence over the value in the <line-termination> element.

Yes Yes

Figure 102, shows an XML sample request for the Kerberized SSH adapter with a Java client. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

124

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (Java client)adapter response

In this case, the first target references the adapter configuration and the second target is a dynamic target. Figure 102 XML sample of the Kerberized SSH adapter request (Java client)
<krb-request> <targets> <target> <user-name>krbuser</user-name> <password>admin123</password> <krb-realm>ABC.COM</krb-realm> <ktgt-cache-file-name>/tmp/krb5cc_515</ktgt-cache-file-name> <kdc-name>matrix-old.abc.com</kdc-name> <host>matrix-old.abc.com</host> <prompt>$</prompt> </target> </targets> <commands> <command>cd /tmp</command> <command>pwd</command> <command>ls -la</command> <command>pwd</command> </commands> </krb-request>

Kerberized SSH adapter (Java client)adapter response

Table 32 describes the elements of a Kerberized SSH adapter response. Table 32
Element <requestmetadata> <status>

Elements of a of a Kerberized SSH adapter response to a request with a Java client (part 1 of 2)
Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targets-output> <target-output>

Contains the command output for all the targets Contains the command output for a specific target A host attribute provides the host name or the IP address of the target.

<target-metadata> Contains the target level summary information <os-id> <os-version> Indicates the operating system type of the target Indicates the operating system version of the target

Chapter 3

Using Terminal adapters

125

Kerberized SSH adapter (Java client)adapter response

Table 32
Element

Elements of a of a Kerberized SSH adapter response to a request with a Java client (part 2 of 2)
Description Indicates the architecture of the target system This element is absent if the target system does not have a defined architecture.

<os-arch>

<status>

Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commands-output> Contains the command responses for all the commands executed on the target computer <command-output> <metadata> <command> <line-count> <executionmilliseconds> <exit-code> Contains the command response for a specific command Contains the command summary information Specifies the command executed Specifies the number of lines returned by the command Specifies the duration of the command execution, in milliseconds Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. Note: If the value returned for the <exit-code> is not 0 or 9999, the value of the <status> element is error, and an <error> element is present in the response. <status> Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> <line> Contains the lines that result from the command Specifies the output resulting from the command An index attribute indicates the sequence in which the line is returned. This can contain any response returned when the <exit-code> is nonzero.

126

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (Java client)adapter response

Figure 103 illustrates the adapter response for the Kerberized SSH adapter with a Java client. Figure 103 XML sample of the Kerberized SSH adapter response (Java client) (part 1 of 3)
<metadata> <status>success</status> </metadata> <targets-output> <target-output host="matrix-old.abc.com"> <metadata> <os-id>Linux</os-id> <os-version>2.6.18-8.el5</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>cd /tmp</command> <line-count>1</line-count> <execution-milliseconds>220</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>cd /tmp</command>

Chapter 3

Using Terminal adapters

127

Kerberized SSH adapter (Java client)adapter response

Figure 103 XML sample of the Kerberized SSH adapter response (Java client) (part 2 of 3)
<line-count>1</line-count> <execution-milliseconds>220</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">[krbuser@matrix-old tmp]$</line> </output> </command-output> <command-output> <metadata> <command>pwd</command> <line-count>2</line-count> <execution-milliseconds>233</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">/tmp</line> <line index="2">[krbuser@matrix-old tmp]$</line> </output> </command-output> <command-output> <metadata> <command>ls -la</command> <line-count>14</line-count> <execution-milliseconds>239</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">[00mtotal 48</line> <line index="2">drwxrwxrwt 6 root root 4096 Aug 19 04:02 [30;42m.[00m</line> <line index="3">drwxr-xr-x 25 root root 4096 Jul 19 14:06 [01;34m..[00m</line> <line index="4">drwxrwxrwt 2 root root 4096 Jul 14 14:03 [30;42m.fontunix[00m</line> <line index="5">srw-rw-rw- 1 root root 0 Jul 14 14:03 [01;35m.gdm_socket[00m</line> <line index="6">drwxrwxrwt 2 root root 4096 Jul 14 14:03 [30;42m.ICEunix[00m</line> <line index="7">-rw------- 1 root root 929 Aug 17 16:11 [00mkrb5cc_0[00m</line> <line index="8">-rw------- 1 ranjana ranjana 946 Aug 16 18:41 [00mkrb5cc_504[00m</line> <line index="9">-rw------- 1 krbuser krbuser 946 Aug 17 17:00 [00mkrb5cc_515[00m</line> <line index="10">drwxrwxrwx 2 root root 4096 Aug 17 16:24 [34;42m.pk11ipc1[00m</line> <line index="11">srwxrwxrwx 1 root root 0 Aug 5 18:10 [01;35mSTAFIPC_STAF[00m</line> <line index="12">-r--r--r-- 1 root root 11 Jul 14 14:03 [00m.X0lock[00m</line> <line index="13">drwxrwxrwt 2 root root 4096 Jul 14 14:03 [30;42m.X11unix[00m</line>

<line index="14">[m[krbuser@matrix-old tmp]$</line>

</output> </command-output> <command-output> <metadata> <command>pwd</command> <line-count>2</line-count> <execution-milliseconds>116</execution-milliseconds>

128

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (local client)adapter configuration

Figure 103 XML sample of the Kerberized SSH adapter response (Java client) (part 3 of 3)
<exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">/tmp</line> <line index="2">[krbuser@matrix-old tmp]$</line> </output> </command-output> </commands-output> </target-output> </targets-output> </kerberos-ssh2-response>

Kerberized SSH adapter (local client)adapter configuration

In addition to targets defined in the adapter configuration, the Kerberized SSH adapter can have dynamic targets defined in each adapter request. If a dynamic target is always defined in the Kerberized SSH adapter request, a configuration node, <config/> can be used in the adapter configuration. Adapter type: ro-adapter-kerberos-ssh1[version] Default adapter name: KerberosSSH1Adapter To configure the Kerberized SSH adapter (local client), see Configuring the adapter on page 14. Table 33 describes the adapter configuration elements for the Kerberized SSH adapter (local client) that you can specify by 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. Table 33
UI Field Target

Configuration node elements for the Kerberized SSH adapter with local client (part 1 of 3)
Element <target> Description Specifies the host name or the IP address of the remote host Required Yes

Note: If the host name provided is not a Fully Qualified Domain Name (FQDN), this shortened host name, not the FQDN, must exist in the Kerberos database. Port <port> Specifies the port on which the remote host listens Default value: 22 Ktgt Cache Filename <ktgtcachefilename> Specifies the name of the file used to cache the Kerberos ticket Conditional No

Chapter 3

Using Terminal adapters

129

Kerberized SSH adapter (local client)adapter configuration

Table 33
UI Field Ssh Command

Configuration node elements for the Kerberized SSH adapter with local client (part 2 of 3)
Element <sshcommand> Description Specifies the location of the SSH client executable Default value: ssh Note: This value is typically not defined. The SSH client executable is most commonly located in a directory specified in the PATH environment variable. This value is only needed when the executable is aliased or present in a non-standard location. Required No

Ssh Options

<sshoptions>

Contains one or more <ssh-option> elements The <ssh-options> element is required when one or more <ssh-option> elements are defined.

Conditional

Ssh Option

<sshoption>

Specifies the available SSH option The sample values are:

s s

No

GSSAPIAuthentication=yes GSSAPIDelegateCredentials=yes

Note: Refer to the Man pages for the SSH client executable to obtain a list of all possible options. Ssh Arguments <ssharguments> Contains one or more <ssh-argument> elements The <ssh-arguments> element is required when one or more <ssh-argument> elements are defined. Ssh Argument <sshargument> Specifies an available SSH argument The sample values are: -t, -v If a prompt is specified in the configuration or in the request, -t,-t must be provided as the argument. This informs the SSH server to open a pseudo terminal session, which is required for the successful execution of prompt-based requests. Note: Multiple arguments can be provided in a single element or multiple elements can be defined, each with a single argument. If multiple arguments are provided in a single element, the arguments must be separated by a space. Refer to the Man pages for the SSH client executable to obtain a list of all possible options. Prompt <prompt> Specifies the console prompt displayed when the system is waiting for a command The <prompt> element is required when using the proxy command feature. If this value is not provided, each command is executed in a separate session, as if each was executed in a new command shell. Note: This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. Conditional No Conditional

130

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (local client)adapter request

Table 33
UI Field

Configuration node elements for the Kerberized SSH adapter with local client (part 3 of 3)
Element <timeoutsecs> Description Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. Default value: 60 seconds Required No

Timeout Secs

Establish Connection Timeout Secs

<establish- Specifies the time, in seconds, to wait for user authentication No connection- on the target server. If authentication is not successful within this time, an error message is returned. timeoutsecs> Default value: 60 seconds

Figure 104 shows an XML template of the adapter configuration for the Kerberized SSH adapter with a local client using the <krb-cache-file> element. Figure 104 XML template of the Kerberized SSH adapter configuration (local client) using <ktgtcache-file>
<config> <target></target> <port></port> <ktgt-cache-file-name></ktgt-cache-file-name> <ssh-command></ssh-command> <ssh-options> <ssh-option></ssh-option> </ssh-options> <ssh-arguments> <ssh-argument></ssh-argument> </ssh-arguments> <prompt></prompt> <timeout-secs></timeout-secs> <establish-connection-timeout-secs></establish-connection-timeout-secs> </config>

Kerberized SSH adapter (local client)adapter request

The Kerberized SSH adapter does not use an action. You must leave the adapters Action field blank when configuring the Activity properties for a Call Adapter Activity in BMC Atrium Orchestrator Development Studio. To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. Partial information cannot be retrieved from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

Chapter 3

Using Terminal adapters

131

Kerberized SSH adapter (local client)adapter request

When you create the adapter request in the Transform Editor, the template must be enclosed within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 34 describes the adapter request elements for the Kerberized SSH adapter with a local client. Table 34
Element <prompts>

Adapter request elements of the Kerberized SSH adapter (local client) (part 1 of 3)
Description Contains additional <prompt> elements that might be needed to execute commands properly The <prompts> element is required when one or more <prompt> elements are defined. Note: This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. Required Conditional

<prompt>

Displays the console prompt when the system is waiting for a command A name attribute specifies the <prompt> value in a <command> element. In the absence of a value for this element, the <prompt> defined in the configuration node or the dynamic target is used.

No

<targets>

Contains the <target> elements This element is required if a target is referenced or defined in the request.

Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If this value is not provided, the default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required when defining a dynamic target.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

No

<ktgtSpecifies the location of a valid Kerberos Ticket Granting Ticket (TGT) cache-filename>

Yes

132

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (local client)adapter request

Table 34
Element <sshcommand>

Adapter request elements of the Kerberized SSH adapter (local client) (part 2 of 3)
Description Specifies the location of the SSH client executable This value is typically not defined. The SSH client executable is most commonly located in a directory specified in the PATH environment variable. This value is needed only when the executable is aliased or present in a non-standard location. Default value: ssh Required No

<sshoptions>

Contains one or more <ssh-option> elements The <ssh-options> element is required when one or more <sshoption> elements are defined.

Conditional

<sshoption>

Specifies an available SSH option The sample values are:

s s

No

GSSAPIAuthentication=yes GSSAPIDelegateCredentials=yes

Note: Refer to the Man pages for the SSH client executable to obtain a list of all possible options. <ssharguments> Contains one or more <ssh-argument> elements The <ssh-arguments> element is required when one or more <sshargument> elements are defined. <sshargument> Specifies an available SSH argument The sample values are: -t, -v If a prompt is specified in the configuration or the request, -t,-t must be provided as the argument. This informs the SSH server to open a pseudo terminal session, which is required for the successful execution of prompt-based requests. Note: Multiple arguments can be provided in a single element or multiple elements can be defined, each with a single argument. If multiple arguments are provided in a single element, the arguments must be separated by a space. Refer to the Man pages for the SSH client executable to obtain a list of all possible options. <prompt> Displays the console prompt when the system is waiting for a command This element applies to a dynamic target and is required when using the proxy command feature. If this element is not provided, each command is executed in a separate session, as if each was executed in a new command shell. This element indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. Conditional No Conditional

Chapter 3

Using Terminal adapters

133

Kerberized SSH adapter (local client)adapter request

Table 34
Element

Adapter request elements of the Kerberized SSH adapter (local client) (part 3 of 3)
Description Required Specifies the time, in seconds, to wait for the expected prompt to be returned Conditional If the expected prompt is not returned before the specified period has elapsed, an error message is returned. This element applies to a dynamic target. Default value: 60 seconds

<timeoutsecs>

<establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned. Default value: 60 seconds <commands> <command> Contains the <command> elements Specifies the command to be executed on the remote host The command must be entered as if it were being keyed at the system prompt.

No

Yes Yes

Figure 105 shows an XML sample request for the Kerberized SSH adapter with a local client. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. In this sample, the first target references the adapter configuration and the second target is a dynamic target.

134

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (local client)adapter response

Figure 105 XML sample of the Kerberized SSH adapter request (local client)
<krb-request> <prompts> <prompt name ="prompt 1">user1-></prompt> </prompts> <targets> <target name="host1"/> <target> <host>server2</host> <port>2200</port> <ktgt-cache-file-name></ktgt-cache-file-name> <ssh-command></ssh-command> <ssh-options> <ssh-option>GSSAPIAuthentication=yes</ssh-option> </ssh-options> <ssh-arguments> <ssh-argument>-t -v</ssh-argument> </ssh-arguments> <prompt>pr1</prompt> <timeout-secs>120</timeout-secs> <establish-connection-timeout-secs>90</establish-connection-timeoutsecs> </target> </targets> <commands> <command prompt="prompt 1">ls -l</command> <command prompt="prompt 1">pwd</command> </commands> </krb-request>

Kerberized SSH adapter (local client)adapter response

Table 35 describes the elements of a Kerberized SSH adapter response to a request with a local client. Table 35
Element <requestmetadata> <status>

Elements of a Kerberized SSH adapter response (local client) (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error.

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <os-id>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the operating system type of the target

Chapter 3

Using Terminal adapters

135

Kerberized SSH adapter (local client)adapter response

Table 35
Element

Elements of a Kerberized SSH adapter response (local client) (part 2 of 2)

Description Indicates the operating system version of the target Indicates the architecture of the target system This element is absent if the target system does not have a defined architecture.

<os-version> <os-arch>

<status>

Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <command> <line-count>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the command executed Specifies the number of lines returned by the command

executionSpecifies the duration of the command execution, in milliseconds milliseconds> <exit-code> Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. Note: If the value returned for the <exit-code> is not 0 or 9999, the value of the <status> element is error, and an <error> element is present in the response. <status> Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of the command is interrupted When the value of the <status> element is success, this element is absent. <output> <line> Contains the lines that result from the command Specifies the output resulting from the command The index attribute indicates the sequence in which the line is returned. This can contain a response returned when the <exit-code> is nonzero.

136

BMC Atrium Orchestrator Base Adapters User Guide

Kerberized SSH adapter (local client)adapter response

Figure 106 illustrates the adapter response for the Kerberized SSH adapter with a local client. Figure 106 XML sample of the Kerberized SSH adapter response (local client)
<kerberos-ssh-command-output> <request-metadata> <status>success</status> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <os-id>Linux</os-id> <os-version>2.6.12-1.1381_FC3smp</os-version> <status>success</status> </target-metadata> <commands-output> <command-output> <metadata> <command>first command executed</command> <line-count>2</line-count> <execution-milliseconds>value</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">line 1</line> <line index="2">line 2</line> </output> </command-output> <command-output> <metadata> <command>second command executed</command> <line-count>1</line-count> <execution-milliseconds>value</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">line 1</line> </output> </command-output> </commands-output> </target-output> </targets-output> </kerberos-ssh-command-output>

Chapter 3

Using Terminal adapters

137

Telnet adapter

Telnet adapter
The Telnet adapter executes commands on a remote host using the Telnet protocol. The Telnet adapter can use the following common features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s s

s s s s s

Multiple Configuration nodes Dynamic Targets FAT CommandsCommand attributes: encryption-type timeout-secs continue-on-failure disable-line-termination is-special-character ignore-exit-code ignore-response os-id os-version Password attribute: encryption-type Verification of OS Persistent Connectivity Proxy Commands Verification of OS

Telnet adapter configuration

In addition to targets defined in the adapter configuration, the Telnet adapter can have dynamic targets defined in each adapter request. If a dynamic target is always defined in the Telnet adapter request, a configuration node, <config/> is used in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-telnet[version] Default adapter name: TelnetAdapter To configure the Telnet adapter, see Configuring the adapter on page 14.

138

BMC Atrium Orchestrator Base Adapters User Guide

Telnet adapter configuration

Table 36 describes the adapter configuration elements for the Telnet adapter that you can specify by 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. Table 36
UI label Target Port

Configuration node elementsTelnet adapter (part 1 of 2)

Element <target> <port> Description Specifies the host name or the IP address of the remote host Specifies the port on which the remote host listens Default value: 23 Required Yes No

User Name

<user-name>

Specifies the user name to be used for remote host authentication The requirements of the user's environment determine whether the <user-name> element is required.

Conditional

Password

<password>

Conditional Specifies the password that corresponds to the <user-name> provided or that used for remote host authentication The requirements of the user's environment determine whether the <password> element is required.

Prompt

<prompt>

Displays the console prompt when the system is waiting for a command This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues.

Yes

Timeout Secs

<timeoutsecs>

Specifies the time, in seconds, to wait for the expected No prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. Default value: 60 seconds

Login Prompt

<loginprompt>

Displays the console prompt when the system is waiting for a user name Default value: Login

No

Chapter 3

Using Terminal adapters

139

Telnet adapter configuration

Table 36
UI label Password Prompt

Configuration node elementsTelnet adapter (part 2 of 2)

Element <passwordprompt> Description Displays the console prompt that is displayed when the system is waiting for a password Default value: Password This element supports multiple attributes as follows:
s

Required No

use-default: With a value of true, the default password-prompt, Password, is used num-password-prompt-occurrences: Allows you to specify a positive numeric value to indicate the number of prompts that will occur in the response when the user name is submitted pre-prompt-command: Allows you to enter one or more commands, often carriage returns, before the user sees the prompt pre-prompt-command-delay-secs: Specifies the delay, in seconds, prior to the invocation of the pre-prompt-command Default value: 60

trim-pre-prompt-command: Removes leading and trailing white spaces from the pre-promptcommand Valid values: true, false (default)

Character Set

<characterset>

Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters. Default value: ISO-8859-2

No

Figure 107 shows an XML configuration template for the Telnet adapter. Figure 107 XML template of the Telnet adapter configuration
<config> <target></target> <port></port> <user-name></user-name> <password></password> <prompt></prompt> <timeout-secs></timeout-secs> <login-prompt></login-prompt> <password-prompt></password-prompt> </config>

140

BMC Atrium Orchestrator Base Adapters User Guide

Telnet adapter request

Figure 108 shows an XML configuration sample for the Telnet adapter with multiple configs. Figure 108 XML sample of the Telnet adapter configuration with multiple configs
<configs> <config name="host1"> <target>host1</target> <port>23</port> <user-name>user1</user-name> <password>pass</password> <prompt>user1$</prompt> </config> <config name="host2"> <target>host2</target> <port>23</port> <user-name>user</user-name> <password>pass</password> <prompt>user2$</prompt> </config> </configs>

Figure 109 shows an XML configuration sample for Telnet adapter with the CharSet element. Figure 109 XML sample of the Telnet adapter configuration with CharSet
<config> <target>server1</target> <user-name>user</user-name> <password>test</password> <prompt>&gt;</prompt> <login-prompt>login:</login-prompt> <password-prompt>password:</password-prompt> <character-set>Shift_JIS</character-set> </config>

Telnet adapter request

The Telnet adapter does not use an action. You must leave the Action field of the adapter blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

Chapter 3

Using Terminal adapters

141

Telnet adapter request

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 37 describes the adapter request elements for the Telnet adapter. Table 37
Element <prompts>

Adapter request elements for the Telnet adapter (part 1 of 2)

Description Contains additional <prompt> elements that are needed to execute commands properly The <prompts> element is required when one or more <prompt> elements are defined. Required Conditional

<prompt>

Displays the console prompt when the system is waiting for a command The name attribute of the <prompt> element is used to specify the value in a <command> element. The <prompt> element indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. In the absence of a value for this element, the <prompt> defined in the configuration node or the dynamic target is used.

No

<targets>

Contains the <target> elements This element is required if a target is referenced or defined in the request.

Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required to define a dynamic target.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 23

Conditional

<user-name> Specifies the user name for remote host authentication This element applies to a dynamic target. The requirements of the user's environment determine whether the <user-name> element is required. <password> Specifies the password that corresponds to the <user-name> provided or that used for remote host authentication This element applies to a dynamic target. The requirements of the user's environment determine whether the <password> element is required

Conditional

Conditional

142

BMC Atrium Orchestrator Base Adapters User Guide

Telnet adapter request

Table 37
Element <prompt>

Adapter request elements for the Telnet adapter (part 2 of 2)

Description Specifies the console prompt displayed when the system is waiting for a command This prompt indicates the completion of command execution. It must be unique, not matching potential command output to prevent parsing issues. This element is required when defining a dynamic target. Required Conditional

<timeoutsecs>

Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned. This element applies to a dynamic target. Default value: 60 seconds

Conditional

<loginprompt>

Displays the console prompt, when the system is waiting for a user name This element applies to a dynamic target Default value: Login

Conditional

<passwordprompt>

Displays the console prompt, when the system is waiting for a password This element applies to a dynamic target Default value: Password

Conditional

<commands> <command>

Contains the <command> elements Specifies the commands to be executed on the remote host The prompt name attribute is used to define the prompt name.

Yes Yes

<connection Allows to change the prompt every time a connection is established, by running a command to change the prompt as the first command after the initialize- session is opened command> This element is supported only in case of named connection (persistent connectivity) You can specify any command within this tag which will get executed while initializing the connection <character- Specifies the supporting CharSet set> CharSet is also called Character Set that includes identifiers describing a series of universal characters.

No

No

Figure 110 shows an XML template for the Telnet adapter request.

Chapter 3

Using Terminal adapters

143

Telnet adapter request

Figure 110 XML template of the Telnet adapter request

<telnet-request> <prompts> <prompt name=""></prompt> </prompts> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <prompt></prompt> <timeout-secs></timeout-secs> <login-prompt></login-prompt> <password-prompt></password-prompt> </target> </targets> <commands> <command prompt =""></command> </commands> </telnet-request>

Figure 111 shows the XML sample of the Telnet adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. In this case, the first target references the adapter configuration and the second target is a dynamic target. Figure 111 XML sample of the Telnet adapter request
<telnet-request> <prompts> <prompt name="P1">/usr/bin></prompt> </prompts> <targets> <target name="host1"/> <target> <host>server3</host> <port>2300</port> <user-name>user</user-name> <password>test</password> <prompt>user1$</prompt> <timeout-secs>120</timeout-secs> <login-prompt>user-name:</login-prompt> <password-prompt>password for user1:</password-prompt> <connection> <name>target1_connection</name> <terminate-on-exit>false</terminate-on-exit> <connection-initialize-commands> <command prompt="%" ignore-response = "true">prompt %</command> <command prompt="%" ignore-response = "true">cd Cookies</command> </connection-initialize-commands> </connection> </target> </targets> <commands> <command prompt="P1">ls -l</command> </commands> </telnet-request>

144

BMC Atrium Orchestrator Base Adapters User Guide

Telnet adapter request

NOTE
The command must be entered as if it were being keyed at the system prompt. The adapter appends cmd \c or /bin/sh -c at the beginning of the command as needed.

Figure 112 shows an XML sample of the Telnet adapter with the CharSet element. Figure 112 XML sample of the Telnet adapter with CharSet
<telnet-request> <targets> <target> <host>server1</host> <user-name>user</user-name> <password>test</password> <prompt>></prompt> <login-prompt>login:</login-prompt> <password-prompt>password:</password-prompt> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <command>type testFile.txt</command> </commands> </telnet-request>

Figure 113 shows an XML sample of the Telnet adapter request for multiple configurations. Figure 113 XML sample of the Telnet adapter request for multiple configurations
<telnet-request> <targets> <target name="host2" /> </targets> <commands> <command working-dir="/" timeout-secs="2">ls -l</command> <command timeout-secs="1">pwd</command> </commands> </telnet-request>

Chapter 3

Using Terminal adapters

145

Telnet adapter response

Figure 114 shows an XML sample of the Telnet adapter request with multiple commands. Figure 114 XML sample of the Telnet adapter request with multiple commands
<telnet-request> <prompts> <prompt name="prompt">${Prompt}</prompt> </prompts> <targets> <target name=""> <host>${target1_host}</host> <userName>${target1_username}</userName> <password>${target1_password}</password> <prompt>${Prompt}</prompt> <login-prompt>${loginprompt}</login-prompt> <password-prompt>${passwordprompt}</password-prompt> </target> </targets> <commands> <command>${Command}</command> <command>${Command1}</command> </commands> </telnet-request>

Telnet adapter response

The Telnet adapter returns an adapter response containing the details for the command executed by the adapter request. Table 38 describes the elements of a Telnet adapter response. Table 38
Element <requestmetadata> <status>

Elements of a Telnet adapter response (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error.

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <os-id>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the operating system type of the target

146

BMC Atrium Orchestrator Base Adapters User Guide

Telnet adapter response

Table 38
Element

Elements of a Telnet adapter response (part 2 of 2)

Description Indicates the operating system version of the target Indicates the architecture of the target system This element is absent if the target system does not have a defined architecture.

<os-version> <os-arch>

<status>

Indicates the status of the target connection Valid values: success, error.

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <command> <line-count>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the command executed Specifies the number of lines returned by the command

<executionSpecifies the duration of the command execution, in milliseconds milliseconds> <exit-code> Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. If the value returned for the <exit-code> is not 0 or 9999, the value of the <status> element is error, and an <error> element is present in the response. <status> Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> <line> Contains the lines resulting from the command Contains the output resulting from the command The index attribute indicates the sequence in which the line is returned. This can contain a response returned when the <exit-code> is nonzero.

Figure 115 illustrates the adapter response for the Telnet adapter.

Chapter 3

Using Terminal adapters

147

Telnet adapter response

Figure 115 XML sample of the Telnet adapter response

<telnet-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <os-id>Linux</os-id> <os-version>2.6.12-1.1381_FC3smp</os-version> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <command>command executed</command> <line-count>1</line-count> <execution-milliseconds>value</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <line index="1">line 1</line> </output> </command-output> </commands-output> </target-output> </targets-output> </telnet-command-output>

148

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter

Figure 116 illustrates the adapter response for the Telnet adapter with multiple commands. Figure 116 XML sample of the Telnet adapter response with multiple commands
<telnet-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="10.128.248.114"> <metadata> <os-id>SunOS</os-id> <os-version>5.10</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ls</command> <line-count>6</line-count> <execution-milliseconds>129</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <command>pwd</command> <line-count>2</line-count> <execution-milliseconds>621</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">/export/home/user1</line> <line index="2">$</line> </output> </command-output> </commands-output> </target-output> </targets-output> </telnet-command-output>]

SCP adapter
The Secure Copy Protocol (SCP) adapter is used to transfer files between a local host and a remote host. The SCP adapter can use the following common features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s s s s s

Multiple Configuration nodes Dynamic Targets Password attribute: encryption-type Persistent Connectivity Known Hosts Public Key Authentication

Chapter 3

Using Terminal adapters

149

SCP adapter configuration

This section describes the configuration, request format, and response format of the SCP adapter:
Available actions SCP adapter configuration SCP adapter response with get action SCP adapter request with get action SCP adapter request SCP adapter request with put action SCP adapter response with put action

SCP adapter configuration

In addition to targets defined in the adapter configuration, the SCP adapter can have a dynamic target defined in each adapter request. If a dynamic target is always defined in the SCP adapter request, a configuration node, <config/> can be used in the adapter configuration. Adapter type: ro-adapter-scp[version] Default adapter name: SCPAdapter To configure the SCP adapter, see Configuring the adapter on page 14. Table 39 describes the adapter configuration elements for the SCP adapter that you can specify by 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. Table 39
UI label Target Port

Configuration node elementsSCP adapter (part 1 of 3)

Element <target> <port> Description Specifies the host name or the IP address of the remote host Specifies the port on which the remote host listens Default value: 22 Required Yes No

User Name Password

<user-name> <password>

Specifies the user name to be used for remote host authentication Specifies the password that corresponds to the <user-name> provided If this element is not provided, the <private-keyfile> can be used

Yes No

Note: This element can contain a encryption-type attribute to indicate whether the password provided is encrypted. Valid values: Base64, Plain (non-encrypted) (default)

150

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter configuration

Table 39
UI label

Configuration node elementsSCP adapter (part 2 of 3)

Element Description Required Identifies the path and the file name for the local SSH Conditional key file This file is used for performing public key authentication. The path and the file must exist on the peer servicing the adapter request. The element can be used in the absence of a <password> element

Private Key File <privatekey-file>

Pass Phrase

<passphrase>

Identifies the passphrase that is used to protect the private key file This element can be used in the absence of a <password> element

Conditional

Note: This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted Valid values (encryption type): Base64, Plain (unencrypted) (default) Timeout Secs <timeoutsecs> Specifies the time, in seconds, to wait for the expected No prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 Known Hosts Config <knownhostsconfig> Identifies the path to the local known_hosts file This file is used for performing key verification Default path: homeDir/.ssh/known_hosts Allow Unknown Hosts <allowunknownhosts> Determines whether a connection must continue if the No key verification fails Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Preferred Pk Algorithm <preferredpkalgorithm> Specifies the preference of the algorithm used to encrypt the public key Valid values: ssh-dss, ssh-rsa (default) No No

Chapter 3

Using Terminal adapters

151

SCP adapter configuration

Table 39
UI label

Configuration node elementsSCP adapter (part 3 of 3)

Element <establishconnectiontimeoutsecs> Description Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned Default value: 60 seconds Required No

Establish Connection Timeout Secs

Network Environment

<networkCreates an extra channel session for use with Sun environment> Solaris 9 This value must be false when connecting to network appliances Valid values: true, false (default)

No

Figure 117 shows the adapter configuration template for the SCP adapter. Figure 117 XML template of the SCP adapter configuration
<configs> <config name=""> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </config> <config name=""> <target></target> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type=""></pass-phrase> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </config> </configs>

Figure 118 shows an XML sample for the SCP adapter configuration.

152

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter request

Figure 118 XML sample of the SCP adapter configuration

<config name="host1"> <target>10.10.75.88</target> <port /> <user-name>asdf</user-name> <password encryption-type="plain">pass</password> <timeout-secs>60</timeout-secs> <known-hosts-config>/home/user2/.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 /> </config>

SCP adapter request

The SCP adapter uses get or put. The SCP adapter requests and responses are actionspecific, and the samples and templates for each action are provided in the following sections. The action indicated must be entered in the adapters Action field in the Property panel of the Call Adapter activity. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

SCP adapter request with get action

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors.

Chapter 3

Using Terminal adapters

153

SCP adapter request with get action

Table 40 describes the adapter request elements for the SCP adapter with get action. Table 40
Element <targets>

Adapter request elementsSCP adapter with get action (part 1 of 2)

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration or contains the elements that defines a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide a value for this element, the default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required when defining a dynamic target.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided If you do not provide the value, the <private-key-file> element can be used. This element can contain a password-encryption attribute to indicate whether the password provided is encrypted Valid values: Base64, Plain (non-encrypted) (default) <privatekey-file> Identifies the path and the file name for the local SSH key file This file is used for performing public key authentication. The element can be used in the absence of a <password> element. The path and file must exist on the peer servicing the adapter request. In addition to the private key file, the .ssh directory on the peer servicing the request must contain the file named authorized_keys or authorized_keys2 <passphrase> Identifies the passphrase that is used to protect the private key file This element can be used in the absence of a <password> element. This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted Valid values (encryption type): Base64, Plain (unencrypted) (default)

Conditional

No

Conditional

Conditional

154

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter request with get action

Table 40
Element

Adapter request elementsSCP adapter with get action (part 2 of 2)

Description Required Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned

<timeoutsecs>

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default path: homeDir/.ssh/known_hosts

Conditional

<allowunknownhosts>

Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error.

Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances.Valid values: true, false (default) <localfile> <remotefile> Specifies the local file path This is the destination file for the get action Specifies the remote file path This is the source file for the get action.

Conditional

No

No

Yes

Yes

Chapter 3

Using Terminal adapters

155

SCP adapter request with get action

Figure 119 shows an XML template of the adapter request for the SCP adapter with get action. Figure 119 XML template of the SCP adapter request with get action
<scp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password encryption-type=""></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </target> <target> <host></host> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type=""></pass-phrase> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </target> </targets> <local-file></local-file> <remote-file></remote-file> </scp-request>

Figure 120 shows an XML sample of the adapter request for the SCP adapter with get action. In this sample, the first target references the adapter configuration and the second target is a dynamic target.

156

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter response with get action

Figure 120 XML sample of the SCP adapter request with get action
<scp-request> <targets> <target name="host1"/> <target> <host>server2</host> <port>2200</port> <user-name>user1</user-name> <password encryption-type="Plain">pass1</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> </target> <target> <host>server3</host> <port>2200</port> <user-name>user1</user-name> <private-key-file>/path/to/SSH key file</private-key-file> <pass-phrase encryption-type="Base64">cGFzczE=</pass-phrase> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> </target> </targets> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </scp-request>

SCP adapter response with get action

The get action request for the SCP adapter returns an adapter response containing the summary information for the action. Table 41 describes the elements of an SCP adapter response to a request with get action. Table 41
Element <requestmetadata> <status>

Elements of an SCP adapter response to a request with get action (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput>

Contains the command output for all the targets

Chapter 3

Using Terminal adapters

157

SCP adapter response with get action

Table 41
Element <targetoutput>

Elements of an SCP adapter response to a request with get action (part 2 of 2)

Description Contains the command output for a specific target The host attribute provides the host name or the IP address of the target.

<targetmetadata> <requestaction> <executionmilliseconds> <local-file> <remote-file> <status>

Contains the target level summary information Indicates the action performed by the request Specifies the duration of the execution, in milliseconds Specifies the destination file for the get command Specifies the source file for the get command Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value in the <status> element is success, this element is absent. Note: If the transfer is interrupted, a partial file might exist in the destination location

<output>

Contains any lines that result from the command This command does not return a detailed response.

Figure 121 illustrates an XML sample of the adapter response for the SCP adapter. Figure 121 XML sample of the SCP adapter response with get action
<scp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <request-action>get</request-action> <execution-milliseconds>4000</execution-seconds> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <output/> </target-output> </targets-output> </scp-command-output>

158

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter request with put action

SCP adapter request with put action

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 42 describes the adapter request elements for the SCP adapter with put action. Table 42
Element <targets>

Adapter request elements for the SCP adapter with put action (part 1 of 3)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Contains a name attribute that references a configuration node from the Conditional adapter configuration or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target. Default value: 22

Conditional

<user-name>

Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target.

Conditional

<password>

Specifies the password that corresponds to the <user-name> provided No If you do not provide the value, the <private-key-file> can be used. This element can contain a password-encryption attribute to indicate whether the password provided is encrypted. Valid values: Base64, Plain (non-encrypted) (default)

Chapter 3

Using Terminal adapters

159

SCP adapter request with put action

Table 42
Element

Adapter request elements for the SCP adapter with put action (part 2 of 3)
Description Required

Conditional <private-key- Identifies the path and the file name for the local SSH key file file> This file is used when performing public key authentication. This element can be used in the absence of a <password> element. The path and file must exist on the peer servicing the adapter request <pass-phrase> Identifies the passphrase that is used to protect the private key file This element can be used in the absence of a <password> element. This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted Valid values (encryption type): Base64, Plain (unencrypted) (default) <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds Conditional <known-hosts- Identifies the path to the local known_hosts file config> This file is used when performing key verification. This element applies to a dynamic target Default path: homeDir/.ssh/known_hosts <allowunknownhosts> Determines whether a connection must continue if the key verification fails This element applies to a dynamic target. Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error <preferredSpecifies the preference of the algorithm used to encrypt the public key Conditional pk-algorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establishSpecifies the time, in seconds, to wait for user authentication on the connectiontarget server timeout-secs> If authentication is not successful within this time, an error message is returned Default value: 60 seconds No Conditional Conditional

160

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter request with put action

Table 42
Element

Adapter request elements for the SCP adapter with put action (part 3 of 3)
Description Creates an extra channel session for use with Sun Solaris 9 This value must be false when connecting to network appliances.Valid values: true, false (default) Required No

<networkenvironment>

<local-file>

Specifies the local file path This is the file source for the put action

Yes

<remote-file> Specifies the remote file path This is the destination file for the put action

Yes

Figure 122 shows an XML template of the adapter request for the SCP adapter with put action. Figure 122 XML template of the SCP adapter request with put action
<scp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </target> <target> <host></host> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type=""></pass-phrase> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </target> <targets> <local-file></local-file> <remote-file></remote-file> </scp-request>

Chapter 3

Using Terminal adapters

161

SCP adapter response with put action

Figure 123 shows an XML sample of the adapter request for the SCP adapter with put action. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 123 XML sample of the SCP adapter request with put action
<scp-request> <targets> <target name="host1"/> <target> <host>server2</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> </target> <target> <host>server3</host> <port>2200</port> <user-name>user1</user-name> <private-key-file>/path/to/SSH key file</private-key-file> <pass-phrase encryption-type="Base64">cGFzczE=</pass-phrase> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs > <network-environment>true</network-environment> /target> </targets> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </scp-request>

SCP adapter response with put action

The put action request for a SCP adapter returns an adapter response containing the summary information for the action. Table 43 describes the elements of an SCP adapter response to a request with put action. Table 43
Element <requestmetadata> <status>

Elements of an SCP adapter response to a request with put action (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

162

BMC Atrium Orchestrator Base Adapters User Guide

SCP adapter response with put action

Table 43
Element <error>

Elements of an SCP adapter response to a request with put action (part 2 of 2)

Description Indicates the error message returned when the value of the <status> element is error When the value of the <status> value is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <requestaction> <executionmilliseconds> <local-file> remote-file> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the action performed by the request Specifies the duration of the execution, in milliseconds Specifies the source file for the put command Specifies the destination file for the put command Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error When the value of the <status> element is success, this element is absent. Note: If the transfer is interrupted, a partial file might exist in the destination location.

<output>

Contains lines that result from the command This command does not return a detailed response.

Figure 124 illustrates an XML sample of the adapter response for the SCP adapter with put action. Figure 124 XML sample of the SCP adapter response with put action (part 1 of 2)
<scp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1">

Chapter 3

Using Terminal adapters

163

FTP adapter

Figure 124 XML sample of the SCP adapter response with put action (part 2 of 2)
<target-metadata> <request-action>put</request-action> <execution-milliseconds>4000</execution-seconds> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <output/> </target-output> <targets-output> </scp-command-output>

FTP adapter
The FTP adapter is used to transfer files and perform specific commands on a remote target using the FTP protocol. The FTP adapter can use the following common features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s s s s

Multiple Configuration nodes Dynamic Targets Password attribute: encryption-type Persistent Connectivity Command attribute: timeout-secs

This section describes the configuration, request format, and response format of the FTP adapter:

FTP adapter configuration FTP adapter request with append command FTP adapter response with append command FTP adapter request with cdup command FTP adapter response with cdup command FTP adapter request with mkdir command FTP adapter response with mkdir command FTP adapter request with pwd command FTP adapter response with pwd command FTP adapter request with rmdir command FTP adapter response with rmdir command FTP adapter request FTP adapter request with cd command FTP adapter request with ls command

FTP adapter response with cd command FTP adapter response with rename command FTP adapter response with get command FTP adapter request with get command FTP adapter response with ls command FTP adapter request with mode command FTP adapter response with put command FTP adapter request with rename command FTP adapter response with rm command FTP adapter request with stat command FTP adapter response with mode command FTP adapter request with put command FTP adapter response with stat command FTP adapter request with rm command

164

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter configuration

FTP adapter configuration

In addition to targets defined in the adapter configuration, the FTP adapter can have a dynamic target defined in each adapter request. If a dynamic target is always defined in the FTP adapter request, a configuration node, <config/> is used in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-ftp [version] Default adapter name: FTPActorAdapter To configure the FTP adapter, see Configuring the adapter on page 14. Table 44 describes the adapter configuration elements for the FTP adapter that you can specify by 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. Table 44
UI label Target Port

FTP adapter configuration elements (part 1 of 2)

Element <target> <port> Description Specifies the host name or the IP address of the remote host Specifies the port on which the remote host listens Default value: 21 Required Yes No

User Name Password

<user-name> <password>

Specifies the user name to be used for remote host authentication Specifies the password that corresponds to the <user-name> provided

Yes Yes

Note: This element can contain a encryption-type attribute to indicate whether the password provided is encrypted Valid values: Base64, Plain (non-encrypted) (default)

Chapter 3

Using Terminal adapters

165

FTP adapter configuration

Table 44
UI label

FTP adapter configuration elements (part 2 of 2)

Element <timeoutsecs> Description Required The time, in seconds, to wait for the expected prompt No to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned. Default value: 60

Timeout Secs

Character Set

<characterset>

Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters. Default value: ISO-8859-2

No

Figure 125 shows an XML template of the FTP adapter configuration. Figure 125 XML template of the FTP adapter configuration
<configs> <config name="host1"> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <timeout-secs></timeout-secs> </config> <config name="host2"> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <timeout-secs></timeout-secs> </config> </configs>

Figure 124 shows an XML sample of the FTP adapter configuration. Figure 126 XML sample of the FTP adapter configuration
<config name="dev4"> <target>192.64.111.222</target> <port>21</port> <userName>name</userName> <password encryption-type="BASE64">password</password> <preferred-pk-algorithm>ssh-rsa</preferred-pk-algorithm> <timeout-secs>5</timeout-secs> </config> <config name="dev3"> <target>192.168.1.1</target> <port>21</port> <userName>name</userName> <password encryption-type="BaSE64">password</password> <preferred-pk-algorithm>ssh-rsa</preferred-pk-algorithm> <timeout-secs>5</timeout-secs> </config>

166

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request

Figure 125 shows an XML sample of the FTP adapter configuration with the Charset element. Figure 127 XML sample of the FTP adapter configuration with Charset element
<config> <target>Server</target> <user-name>user</user-name> <password encryption-type="plain">pass</password> <timeout-secs>120</timeout-secs> <allow-unknown-hosts>true</allow-unknown-hosts> <character-set>Shift_JIS</character-set> </config>

FTP adapter request

The FTP adapter uses the FTP command as tag names in the request. The FTP adapter does not use any actions. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. Sample requests and responses are provided for each of the commands available for this adapter. These samples are basic and do not reflect all the available features for this adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. The commands supported by the FTP adapter are listed in Table 45. Table 45
Command append cd cdup et ls mkdir mode

FTP adapter commands (part 1 of 2) (part 1 of 2)

Description Appends a local file to an existing remote file Changes the directory on the remote server Changes the directory on the remote server to the directory one level above the current directory Obtains a file from the remote server and places it on the local server Lists the files on the remote server Creates a directory on the remote server Sets the transfer mode Valid values: binary, ascii

put pwd rename rm

Transfers a file from the local server to the remote server Prints the working directory on the remote server Changes the name of a file on the remote server Deletes a file from the remote server

Chapter 3

Using Terminal adapters

167

FTP adapter request with a dynamic target

Table 45
Command rmdir stat

FTP adapter commands (part 2 of 2) (part 2 of 2)

Description Deletes a directory from the remote server Obtains the status of a file or directory on the remote server

FTP adapter request with a dynamic target

Figure 128 on page 168 shows an XML sample of the adapter request for the FTP adapter with a dynamic target. Figure 128 XML sample of the FTP adapter request with a dynamic target
<ftp-request> <targets> <target> <host>10.128.248.23</host> <user-name>root</user-name> <password>root@123</password> </target> </targets> <commands> <pwd/> </commands> </ftp-request>

FTP adapter response with a dynamic target

Figure 129 shows an XML sample of the adapter request for the FTP adapter with a dynamic target.

168

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with append command

Figure 129 XML sample of the FTP adapter response with a dynamic target
<ftp-command-output> <response-metadata> <status>success</status> </response-metadata> <targets-output> <target-output host="10.128.248.23"> <target-metadata> <status>success</status> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>pwd</command> <execution-milliseconds>0</execution-milliseconds> <status>success</status> </metadata> <output> <pwd>/root</pwd> </output> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with append command

Table 46 describes the adapter request elements of the FTP adapter with the append command. Table 46
Element <targets>

Adapter request elements of the FTP adapter with append command (part 1 of 2) (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

<datatransfermode> <commands>

Indicates the mode to be used for the FTP data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command and supporting elements

No

Yes

Chapter 3

Using Terminal adapters

169

FTP adapter request with append command

Table 46
Element <append>

Adapter request elements of the FTP adapter with append command (part 2 of 2) (part 2 of 2)
Description Indicates that an append function is performed It also contains the elements defining the local and remote files that are affected. Required Yes

<localfile> <remotefile>

Specifies the local file path, including the file name This is the source file for the append command. Specifies the remote file path, including the file name This is the destination file for the append command.

Yes

Yes

<character- Specifies the supporting CharSet set> CharSet is also called Character Set that includes identifiers describing a series of universal characters.

No

Figure 130 shows an XML template of the adapter request for the FTP adapter with the append command. Figure 130 XML template of the FTP adapter request with append command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <append> <local-file></local-file> <remote-file></remote-file> </append> </commands> </ftp-request>

Figure 131 shows an XML sample of the adapter request for the FTP adapter with the append command. Figure 131 XML sample of the FTP adapter request with append command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>ACTIVE</data-transfer-mode> <commands> <append> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </append> </commands> </ftp-request>

170

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with append command

FTP adapter response with append command

The append command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 47 describes the elements of an FTP adapter response to a request with append action. Table 47
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with append command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

171

FTP adapter request with cd command

Table 47
Element <error>

Elements of an FTP adapter response to a request with append command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains lines that result from the command This command does not return a detailed response.

Figure 132 illustrates an XML sample of the adapter response for the FTP adapter with append action. Figure 132 XML sample of the FTP adapter response with append command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>append</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with cd command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 48 describes the adapter request elements of the FTP adapter with the cd command.

172

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with cd command

Table 48
Element

Adapter request elements of the FTP adapter with cd Command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<targets>

<target>

Contains the name attribute that references a configuration node from Conditional the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

<datatransfer-mode> <commands> <cd>

Indicates the mode to be used for data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command element Indicates the working directory of the remote host With a <cd/> element, the working directory is the home directory.

No

Yes Yes

<characterset>

Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters.

No

Figure 133 shows an XML template of the adapter request for the FTP adapter with cd command. Figure 133 XML template of the FTP adapter request with cd command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <cd></cd> </commands> </ftp-request>

Figure 134 shows an XML sample of the adapter request for the FTP adapter with cd command.

Chapter 3

Using Terminal adapters

173

FTP adapter response with cd command

Figure 134 XML sample of the FTP adapter request with cd command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <cd>/tmp</cd> </commands> </ftp-request>

FTP adapter response with cd command

The cd command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 49 describes the elements of an FTP adapter response to a request with cd command. Table 49
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with cd command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command

174

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with cd command

Table 49
Element

Elements of an FTP adapter response to a request with cd command (part 2 of 2)

Description Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<metadata> <id> <command> <executionmilliseconds> <status>

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 135 illustrates an XML sample of the adapter response for the FTP adapter with cd command. Figure 135 XML sample of the FTP adapter response with cd command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>cd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

Chapter 3

Using Terminal adapters

175

FTP adapter request with cdup command

FTP adapter request with cdup command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 50 describes the adapter request elements for the FTP adapter with the cdup command. Table 50
Element <targets>

Adapter request elementsFTP adapter with cdup command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

Conditional

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <cdup> <characterset> Contains the FTP command element Indicates whether the working directory on the remote host must be changed to a directory one level above the current directory Specifies the supporting CharSet CharSet is also called Character Set that includes identifiers describing a series of universal characters.

No

Yes Yes No

Figure 136 shows an XML template of the adapter request for the FTP adapter with cdup command. Figure 136 XML template of the FTP adapter request with cdup command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <cdup/> </commands> </ftp-request>

176

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with cdup command

Figure 137 shows an XML sample of the adapter request for the FTP adapter with cdup command. Figure 137 XML sample of the FTP adapter request with cdup command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <cdup/> </commands> </ftp-request>

FTP adapter response with cdup command

The cdup command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 51 describes the elements of an FTP adapter response to a request with cdup command. Table 51
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with cdup command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutpu>t <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

Chapter 3

Using Terminal adapters

177

FTP adapter response with cdup command

Table 51
Element

Elements of an FTP adapter response to a request with cdup command (part 2 of 2)

Description Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 138 illustrates an XML sample of the adapter response for the FTP adapter with cdup command. Figure 138 XML sample of the FTP adapter response with cdup command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>cdup</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

178

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with get command

FTP adapter request with get command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 52 describes the adapter request elements for the FTP adapter with get command. Table 52
Element <targets>

Adapter request elements for the FTP adapter with get command
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

Conditional

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <get> Contains the FTP command and supporting elements Indicates that a get function is being performed It also contains the elements defining the local and remote files that are affected. <local-file> Specifies the local file path, including the file name This is the destination file for the get command. If you do not provide the value, the path provided for the remote file is used. For the command to be successful, this path must correspond to a valid path on the local server. <remote-file> Specifies the remote file path, including the file name This is the source file for the get command. <characterset> Specifies the supporting CharSet CharSet is also called Character set that includes identifiers describing a series of universal characters.

No

Yes Yes

No

Yes

No

Figure 139 shows an XML template of the adapter request for the FTP adapter with get command.

Chapter 3

Using Terminal adapters

179

FTP adapter response with get command

Figure 139 XML template of the FTP adapter request with get command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <get> <local-file></local-file> <remote-file></remote-file> </get> </commands> </ftp-request>

Figure 140 shows an XML sample of the adapter request for the FTP adapter with get command. Figure 140 XML sample of the FTP adapter request with get command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <get> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </get> </commands> </ftp-request>

FTP adapter response with get command

The get command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 53 describes the elements of an FTP adapter response to a request with get command. Table 53
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with get command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

180

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with get command

Table 53
Element

Elements of an FTP adapter response to a request with get command (part 2 of 2)

Description Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of command execution Valid values: success, error

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent. Note: If the transfer is interrupted, a partial file might exist in the destination location.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 141 illustrates an XML sample of the adapter response for the FTP adapter with get command.

Chapter 3

Using Terminal adapters

181

FTP adapter request with ls command

Figure 141 XML sample of the FTP adapter response with get command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>get</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with ls command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Table 54 describes the adapter request elements for the FTP adapter with ls command. Table 54
Element <targets>

Adapter request elementsFTP adapter with ls command (part 1 of 2)

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

<datatransfermode> <commands>

Indicates the mode to be used for data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command element

No

Yes

182

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with ls command

Table 54
Element <ls>

Adapter request elementsFTP adapter with ls command (part 2 of 2)

Description Indicates the directory on the remote host for which files must be listed With an <ls/> element, the files in the working directory are listed. Required Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Figure 142 shows an XML template of the adapter request for the FTP adapter with ls command. Figure 142 XML template of the FTP adapter request with ls command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <ls></ls> </commands> </ftp-request>

Figure 143 shows an XML sample of the adapter request for the FTP adapter with ls command. Figure 143 XML sample of the FTP adapter request with ls command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <ls>/tmp</ls> </commands> </ftp-request>

FTP adapter response with ls command

The ls command request for the FTP adapter returns an adapter response containing the details about the files contained in the specified directory.

Chapter 3

Using Terminal adapters

183

FTP adapter response with ls command

Table 55 describes the elements of an FTP adapter response to a request with ls command. Table 55
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with ls command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output> <file> <name> <owner>

Contains the lines that result from the command Contains the detail lines returned for a file in the specified directory Indicates the file name Indicates the file owner

184

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with ls command

Table 55
Element <group>

Elements of an FTP adapter response to a request with ls command (part 2 of 2)

Description Indicates the file group Indicates the file permissions This value consists of 10 characters, in 4 segments. The first segment is a single character that indicates the type, file (-), directory (d), symbolic link (s), or unknown (u). The next three segments are three characters each, representing the read (r), write (w), and execute (x) permissions on the file for the file owner, the group, and others. If no permission is granted, the permissions character is replaced with a hyphen (-) as a placeholder. Example: -rw-r--r-- indicates it is a file, with read and write permissions for the file owner, and read-only permissions for the group and others.

<permission>

<modification- Indicates the time when the file is last modified time> <size-bytes> Indicates the file size, in bytes

Chapter 3

Using Terminal adapters

185

FTP adapter request with mkdir command

Figure 144 illustrates an XML sample of the adapter response for the FTP adapter with ls command. Figure 144 XML sample of the FTP adapter response with ls command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>ls</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <file> <name>Sample File1</name> <owner>user1</owner> <group>tester</group> <permission>-rw-r--r--</permission> <modification-time>Jan 01 01:00</modification-time> <size-bytes>195</size-bytes> </file> ... </output> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with mkdir command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter request because they might cause errors.

186

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with mkdir command

Table 56 describes the adapter request elements for the FTP adapter with mkdir command. Table 56
Element <targets>

Adapter request elements of the FTP adapter with mkdir command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used.

Conditional

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <mkdir> <characterset> Contains the FTP command element Indicates the existing path on the remote server and the name of the directory to be created Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters.

No

Yes Yes No

Figure 145 shows an XML template of the adapter request for the FTP adapter with mkdir command. Figure 145 XML template of the FTP adapter request with mkdir command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <mkdir></mkdir> </commands> </ftp-request>

Chapter 3

Using Terminal adapters

187

FTP adapter response with mkdir command

Figure 146 shows an XML sample of the adapter request for the FTP adapter with mkdir command. Figure 146 XML sample of the FTP adapter request with mkdir command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <mkdir>/path/to/new/directory/directory name</mkdir> </commands> </ftp-request>

FTP adapter response with mkdir command

The mkdir command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 57 describes the elements of an FTP adapter response to a request with mkdir command. Table 57
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with mkdir command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the when the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the when the value of the <status> element is success, this element is absent.

188

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with mkdir command

Table 57
Element

Elements of an FTP adapter response to a request with mkdir command (part 2 of 2)

Description Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

c<ommandsoutput> <commandoutput> <metadata> <id> c<ommand> <executionmilliseconds> <status>

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 147 illustrates an XML sample of the adapter response for the FTP adapter with mkdir command. Figure 147 XML sample of the FTP adapter response with mkdir command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>mkdir</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

Chapter 3

Using Terminal adapters

189

FTP adapter request with mode command

FTP adapter request with mode command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 58 describes the adapter request elements for the FTP adapter with mode command. Table 58
Element <targets>

Adapter request elements of the FTP adapter with mode command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

<datatransfermode> <commands> <mode>

Indicates the mode to be used for data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command element Indicates the transfer mode Valid values: binary, ascii

No

Yes Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Figure 148 shows an XML template of the adapter request for the FTP adapter with mode command. Figure 148 XML template of the FTP adapter request with mode command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <mode></mode> </commands> </ftp-request>

190

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with mode command

Figure 149 shows an XML sample of the adapter request for the FTP adapter with mode command. Figure 149 XML sample of the FTP adapter request with mode command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE or ACTIVE</data-transfer-mode> <commands> <mode>binary or ascii</mode> </commands> </ftp-request>

FTP adapter response with mode command

The mode command request for the FTP adapter returns an adapter response that contains the summary information for the command. Table 59 describes the elements of an FTP adapter response to a request with mode command. Table 59
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with mode command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

Chapter 3

Using Terminal adapters

191

FTP adapter response with mode command

Table 59
Element

Elements of an FTP adapter response to a request with mode command (part 2 of 2)

Description Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 150 illustrates an XML sample of the adapter response for the FTP adapter with mode command. Figure 150 XML sample of the FTP adapter response with mode command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>mode</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

192

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with put command

FTP adapter request with put command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 60 describes the adapter request elements of the FTP adapter with put command. Table 60
Element <targets>

Adapter request elements of the FTP adapter with put Command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

<datatransfermode> <commands> <put>

Indicates the mode to be used for data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command and supporting elements Indicates if the put function is performed It also contains the elements defining the local and remote files that are affected.

No

Yes Yes

<localfile> <remotefile>

Specifies the local file path, including the file name This is the source file for the put command. Specifies the remote file path, including the file name This is the destination file for the put command. If you do not provide the value, the path provided for the local file is used. This path must correspond to a valid path on the remote server to be successful.

Yes

No

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Figure 151 shows an XML template of the adapter request for the FTP command with put command.

Chapter 3

Using Terminal adapters

193

FTP adapter response with put command

Figure 151 XML template of the FTP adapter request with put command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <put> <local-file></local-file> <remote-file></remote-file> </put> </commands> </ftp-request>

Figure 152 shows an XML sample of the adapter request for the FTP adapter with put command. Figure 152 XML sample of the FTP adapter request with put command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <put> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </put> </commands> </ftp-request>

FTP adapter response with put command

The put command request for a FTP adapter returns an adapter response containing the summary information for the command. Table 61 describes the elements of an FTP adapter response to a request with put command. Table 61
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with put command (part 1 of 2) (part 1 of 2)
Description Contains the request level summary information Indicates the status of the request Valid values: success, error

194

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with put command

Table 61
Element <error>

Elements of an FTP adapter response to a request with put command (part 2 of 2) (part 2 of 2)
Description Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent. Note: If the transfer is interrupted, a partial file might exist in the destination location.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Chapter 3

Using Terminal adapters

195

FTP adapter request with pwd command

Figure 153 illustrates an XML sample of the adapter request for the FTP adapter with put command. Figure 153 XML sample of the FTP adapter response with put command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>put</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with pwd command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 62 describes the adapter request elements of the FTP adapter with pwd command. Table 62
Element <targets>

Adapter request elements of the FTP adapter with pwd command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used.

Conditional

196

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with pwd command

Table 62
Element

Adapter request elements of the FTP adapter with pwd command (part 2 of 2)
Description Required No

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <pwd> <characterset> Contains the FTP command element Indicates the present working directory Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters.

Yes Yes No

Figure 154 shows an XML template of the adapter request for the FTP adapter for the pwd command. Figure 154 XML template of the FTP adapter request with pwd command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <pwd/> </commands> </ftp-request>

Figure 155 shows an XML sample of the adapter request for the FTP adapter with pwd command. Figure 155 XML sample of the FTP adapter request with pwd command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <pwd/> </commands> </ftp-request>

FTP adapter response with pwd command

The pwd command request for the FTP adapter returns an adapter response that contains the present working directory. Table 63 describes the elements of an FTP adapter response to a request with pwd command.

Chapter 3

Using Terminal adapters

197

FTP adapter response with pwd command

Table 63
Element

Elements of an FTP adapter response to a request with pwd command

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<requestmetadata> <status>

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput>

Contains the command output for all the targets

<target-output> Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. <targetmetadata> <status> Contains the target level summary information Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commandsoutput> <commandoutput> <metadata> id> <command> <executionmilliseconds> <status> Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> <pwd> Contains the lines that result from the command Indicates the present working directory

198

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with rename command

Figure 156 illustrates an XML template of the adapter response for the FTP adapter with pwd command. Figure 156 XML template of the FTP adapter response with pwd command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>pwd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <pwd>/tmp</pwd> </output> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with rename command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

Chapter 3

Using Terminal adapters

199

FTP adapter request with rename command

Table 64 describes the adapter request elements of the FTP adapter with rename command. Table 64
Element <targets>

Adapter request elementsFTP adapter with rename command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used

Conditional

<datatransfermode> <commands> <rename> <old-file>

Indicates the mode to be used for data transfer Valid values: PASSIVE, ACTIVE (default) Contains the FTP command and supporting elements Indicates the file to be renamed and contains the elements defining the existing and new file names Specifies the remote file path, including the file name of the existing file This is the file that is renamed

No

Yes Yes Yes

<new-file> <characterset>

Specifies the remote file path, including the new file name Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters

Yes No

Figure 157 shows an XML template of the adapter request for the FTP adapter with rename command. Figure 157 XML template of the FTP adapter request with rename command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <rename> <old-file></old-file> <new-file></new-file> </rename> </commands> </ftp-request>

Figure 158 shows an XML sample of the adapter request for the FTP adapter with the rename command.

200

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with rename command

Figure 158 XML sample of the FTP adapter request with rename command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <rename> <old-file>/path/to/file/filename</old-file> <new-file>/path/to/file/new filename</new-file> </rename> </commands> </ftp-request>

FTP adapter response with rename command

The rename command request for the FTP adapter returns an adapter response containing the summary information for the command. Table 65 describes the elements of an FTP adapter response to a request with rename command. Table 65
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with rename command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput>

Contains the command responses for all the commands executed on the target computer

Chapter 3

Using Terminal adapters

201

FTP adapter response with rename command

Table 65
Element

Elements of an FTP adapter response to a request with rename command (part 2 of 2)

Description Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 159 illustrates the adapter response for the FTP adapter with rename command. Figure 159 XML sample of the FTP adapter response with rename command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>rename</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

202

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with rm command

FTP adapter request with rm command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 66 describes the adapter request elements for the FTP adapter with rm command. Table 66
Element <targets>

Adapter request elements of the FTP adapter with rm command

Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Contains a name attribute that references a configuration node from the Conditional adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If not provided, the default target in the adapter configuration is used

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <rm> <characterset> Contains the FTP command element Indicates the remote path and the file name for the file to be removed from the remote server Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters

No

Yes Yes No

Figure 160 shows an XML template of the adapter request for the FTP adapter with rm command. Figure 160 XML template of the FTP adapter request with rm command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <rm></rm> </commands> </ftp-request>

Chapter 3

Using Terminal adapters

203

FTP adapter response with rm command

Figure 161 shows an XML sample of the adapter request for the FTP adapter with rm command. Figure 161 XML sample of the FTP adapter request with rm command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <rm>/path/to/file/filename</rm> </commands> </ftp-request>

FTP adapter response with rm command

The rm command request for the FTP adapter returns an adapter response containing the summary information for the command. Table 67 describes the elements of an FTP adapter response to a request with rm command. Table 67
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with rm command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

204

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with rm command

Table 67
Element

Elements of an FTP adapter response to a request with rm command (part 2 of 2)

Description Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<commandsoutput> <commandoutput> <metadata> <id> <command> executionmilliseconds> <status>

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains any lines that result from the command This command does not return a detailed response.

Figure 162 illustrates an XML sample of the adapter response for the FTP adapter with rm command. Figure 162 XML sample of the FTP adapter response with rm command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>rm</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

Chapter 3

Using Terminal adapters

205

FTP adapter request with rmdir command

FTP adapter request with rmdir command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 68 describes the adapter request elements of the FTP adapter with the rmdir command. Table 68
Element <targets>

Adapter request elements of the FTP adapter with rmdir command

Description Contains the <target> elements This element is required if a target computer is referenced or defined in the request Required Conditional

<target>

Contains a name attribute that references a configuration node from the Conditional adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target computer is referenced or defined in the request. If not provided, the default target in the adapter configuration is used

<dataIndicates the mode to be used for data transfer transfer-mode> Valid values: PASSIVE, ACTIVE (default) <commands> <rmdir> <characterset> Contains the FTP command element Indicates the remote path for the directory to be removed from the remote server Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters

No

Yes Yes No

Figure 163 shows an XML template of the adapter request for the FTP adapter with rmdir command. Figure 163 XML template of the FTP adapter request with the rmdir command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <rmdir></rmdir> </commands> </ftp-request>s

206

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with rmdir command

Figure 164 shows an XML sample of the adapter request for the FTP adapter with the rmdir command. Figure 164 XML sample of the FTP adapter request with rmdir command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <rmdir>/path/to/directory</rmdir> </commands> </ftp-request>

FTP adapter response with rmdir command

The rmdir command request for a FTP adapter returns an adapter response containing the summary information for the command. Table 69 describes the elements of an FTP adapter response to a request with rmdir command. Table 69
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with rmdir command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

Chapter 3

Using Terminal adapters

207

FTP adapter response with rmdir command

Table 69
Element <error>

Elements of an FTP adapter response to a request with rmdir command (part 2 of 2)

Description Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains any lines that result from the command This command does not return a detailed response.

208

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter request with stat command

Figure 165 illustrates an XML sample of the adapter response for the FTP adapter with rmdir command. Figure 165 XML sample of the FTP adapter response with rmdir command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>rmdir</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

FTP adapter request with stat command

The FTP adapter request with stat command is not available in Solaris 8 environments. Table 70 describes the adapter request elements for the FTP adapter with stat command. Table 70
Element

Adapter request elements of the FTP adapter with stat command (part 1 of 2)
Description Required Conditional

<targets> Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target computer is referenced or defined in the request. If this value is not provided, the default target in the adapter configuration is used.

Conditional

Chapter 3

Using Terminal adapters

209

FTP adapter request with stat command

Table 70
Element

Adapter request elements of the FTP adapter with stat command (part 2 of 2)
Description Required No

<dataIndicates the mode to be used for data transfer transfermode> Valid values: PASSIVE, ACTIVE (default) <commands Contains the FTP command element > <stat> Indicates the file for which the status must be returned <characte Specifies the supporting CharSet r-set> CharSet is also called Character set that are identifiers describing a series of universal characters

Yes Yes No

Figure 166 shows an XML template of the adapter request for the FTP adapter with stat command. Figure 166 XML template of the FTP adapter request with stat command
<ftp-request> <targets> <target name=""/> </targets> <data-transfer-mode></data-transfer-mode> <commands> <stat></stat> </commands> </ftp-request>

Figure 167 shows an XML sample of the adapter request for the FTP adapter with stat command. Figure 167 XML sample of the FTP adapter request with stat command
<ftp-request> <targets> <target name="host1"/> <character-set>Shift_JIS</character-set> </targets> <data-transfer-mode>PASSIVE</data-transfer-mode> <commands> <stat>SampleFile1</stat> </commands> </ftp-request>

210

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with stat command

FTP adapter response with stat command

The stat command request for a FTP adapter returns an adapter response containing the status details for the specified file. Table 71 describes the elements of an FTP adapter response to a request with stat command. Table 71
Element <requestmetadata> <status>

Elements of an FTP adapter response to a request with stat command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target computer The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

211

FTP adapter request with multiple commands

Table 71
Element <error>

Elements of an FTP adapter response to a request with stat command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output> <stat>

Contains any lines that result from the command Indicates the status of the specified file

Figure 168 illustrates an XML sample of the adapter response of the FTP adapter with stat command. Figure 168 XML sample of the FTP adapter response with stat command
<ftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>stat</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <stat>213-status of SampleFile1:&#xD; -rw-r--r-1 user1 tester 195 Jan 1 2005 SampleFile1&#xD; Status</stat> </output> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

213 End of

FTP adapter request with multiple commands

Figure 169 shows an XML sample of the adapter request for the FTP adapter with multiple commands.

212

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with multiple commands

Figure 169 XML sample of the FTP adapter request with multiple commands
<ftp-request> <data-transfer-mode>ACTIVE</data-transfer-mode> <commands> <pwd/> <ls>/export/home</ls> </commands> </ftp-request>

FTP adapter response with multiple commands

Figure 170 shows an XML sample of the adapter response for the FTP adapter with multiple commands.

Chapter 3

Using Terminal adapters

213

FTP adapter response with multiple commands

Figure 170 XML sample of the FTP adapter response with multiple commands (part 1 of 3)
<ftp-command-output> <response-metadata> <status>success</status> </response-metadata> <targets-output> <target-output host="10.128.248.114"> <target-metadata> <status>success</status> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>pwd</command> <execution-milliseconds>3</execution-milliseconds> <status>success</status> </metadata> <output> <pwd>/export/home/ranjana</pwd> </output> </command-output> <command-output> <metadata> <id>2</id> <command>ls</command> <execution-milliseconds>32</execution-milliseconds> <status>success</status> </metadata> <output> <file> <name>Lalit</name> <owner>root</owner> <group>root</group> <permission>drwxr-xr-x</permission> <modification-time>Apr 13 15:00</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user1</name> <owner>root</owner> <group>root</group> <permission>drwxrwxrwx</permission> <modification-time>Apr 20 13:38</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user2</name> <owner>user2</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Oct 29 00:00</modification-time> <size-bytes>1024</size-bytes> </file> <file> <name>user3</name> <owner>user3</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Jan 15 14:10</modification-time> <size-bytes>1024</size-bytes> </file> <file>

214

BMC Atrium Orchestrator Base Adapters User Guide

FTP adapter response with multiple commands

Figure 171 XML sample of the FTP adapter response with multiple commands (part 2 of 3)
<name>user4</name> <owner>user4</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Apr 13 15:00</modification-time> <size-bytes>1024</size-bytes> </file> <file> <name>user5</name> <owner>user5</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Oct 29 00:00</modification-time> <size-bytes>1024</size-bytes> </file> <file> <name>user6</name> <owner>user6</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Jan 22 00:00</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user7</name> <owner>root</owner> <group>root</group> <permission>drwxr-xr-x</permission> <modification-time>Feb 23 11:46</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user8</name> <owner>user8</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>May 10 10:58</modification-time> <size-bytes>1024</size-bytes> </file> <file> <name>user9</name> <owner>user9</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Oct 19 00:00</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user9root</name> <owner>root</owner> <group>root</group> <permission>drwxr-xr-x</permission> <modification-time>Dec 10 18:10</modification-time> <size-bytes>512</size-bytes> </file> <file> <name>user10</name> <owner>user10</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Apr 20 13:38</modification-time> <size-bytes>1024</size-bytes> </file> <file> <name>user11</name> <owner>user11</owner> <group>other</group> <permission>drwxrwxr--</permission> <modification-time>May 12 18:33</modification-time> <size-bytes>1024</size-bytes> </file>

Chapter 3

Using Terminal adapters

215

SFTP adapter

Figure 172 XML sample of the FTP adapter response with multiple commands (part 3 of 3)
<file> <name>user12</name> <owner>user12</owner> <group>other</group> <permission>drwxr-xr-x</permission> <modification-time>Dec 16 10:31</modification-time> <size-bytes>1024</size-bytes> </file> </output> </command-output> </commands-output> </target-output> </targets-output> </ftp-command-output>

SFTP adapter
The SFTP adapter is used for secure file transfers and to perform specific commands on a secure target computer using the SFTP protocol. The SFTP adapter can use the following features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s s s s s s

Multiple Configuration nodes Dynamic Targets Password attribute: encryption-type Persistent Connectivity Known Hosts Public Key Authentication Command attribute: timeout-secs

This section describes the configuration, request format, and response format of the SFTP adapter:

SFTP adapter configuration

SFTP adapter request SFTP adapter request with chgrp command

SFTP adapter request with cd command SFTP adapter response with chgrp command SFTP adapter request with chown command SFTP adapter response with get command SFTP adapter request with lcd command SFTP adapter response with lpwd command

SFTP adapter request with chmod command SFTP adapter response with chown command SFTP adapter request with get-dir command SFTP adapter response with lcd command

SFTP adapter response with chmod command SFTP adapter request with get command SFTP adapter response with get-dir command SFTP adapter request with lpwd command

216

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter configuration

SFTP adapter request with ls SFTP adapter response with command ls command SFTP adapter response with mkdir command SFTP adapter request with put command SFTP adapter response with put-dir command SFTP adapter request with rename command SFTP adapter response with rm command SFTP adapter request with mkdirs command SFTP adapter response with put command SFTP adapter request with pwd command SFTP adapter response with rename command SFTP adapter request with symlink command

SFTP adapter request with mkdir command SFTP adapter response with mkdirs command SFTP adapter request with put-dir command SFTP adapter response with pwd command SFTP adapter request with rm command SFTP adapter response with symlink command

SFTP adapter configuration

In addition to targets defined in the adapter configuration, the SFTP adapter can have a dynamic target defined in each adapter request. If a dynamic target is defined in the SFTP adapter request, a configuration node, <config/> can be used in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-sftp[version] Default adapter name: SFTPActorAdapter To configure the SFTP adapter, see Configuring the adapter on page 14. Table 72 describes the adapter configuration elements for the SFTP adapter that you can specify by 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. Table 72
UI label Target Port

Configuration node elementsSFTP adapter (part 1 of 3)

Element <target> <port> Description Specifies the host name or the IP address of the remote host Specifies the port on which the remote host listens Default value: 22 Required Yes No

User Name

<user-name>

Specifies the user name to be used for the remote host Yes authentication

Chapter 3

Using Terminal adapters

217

SFTP adapter configuration

Table 72
UI label Password

Configuration node elementsSFTP adapter (part 2 of 3)

Element <password> Description Specifies the password that corresponds to the <user-name> element provided If you do not provide the value, the <private-keyfile> can be used Valid values: Base64, Plain (non-encrypted) (default) Note: This element can contain a encryption-type attribute to indicate whether the password provided is encrypted Required No

Private Key File <privatekey-file>

Identifies the path and the file name for the local SSH Conditional key file This file is used when performing public key authentication. The element can be used in the absence of a <password> element. This path and file must exist on the peer servicing the adapter request

Pass Phrase

<passphrase>

Identifies the passphrase that is used to protect the private key file The element can be used in the absence of a <password> element Valid values (encryption type): Base64, Plain (unencrypted) (default)

Conditional

Note: This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted Timeout Secs <timeoutsecs> Specifies the time, in seconds, to wait for the expected No prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds Known Hosts Config <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification Default value: homeDir/.ssh/known_hosts Allow Unknown Hosts <allowunknownhosts> Determines whether a connection must continue if key verification fails Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error No No

218

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter configuration

Table 72
UI label

Configuration node elementsSFTP adapter (part 3 of 3)

Element <preferredpkalgorithm> <establishconnectiontimeoutsecs> Description Specifies the preference of the algorithm used to encrypt the public key Valid values: ssh-dss, ssh-rsa (default) Required No

Preferred Pk Algorithm

Establish Connection Timeout Secs

Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned Default value: 60 seconds

No

Network Environment

<networkCreates an extra channel session for use with Sun environment> Solaris 9 This value must be false when connecting to network appliances Valid values: true, false (default)

No

Character Set

<characterset>

Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters Default value: ISO-8859-2

No

Chapter 3

Using Terminal adapters

219

SFTP adapter configuration

Figure 173 shows an XML template of the adapter configuration for the SFTP adapter. Figure 173 XML template of the SFTP adapter configuration
<configs> <config name="host1"> <target></target> <port></port> <user-name></user-name> <password encryption-type=""></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </config> <config name="host2"> <target></target> <port></port> <user-name></user-name> <private-key-file></private-key-file> <pass-phrase encryption-type=""></pass-phrase> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> </config> </configs>

Figure 174 shows an XML sample of the SFTP adapter configuration. Figure 174 XML sample of the SFTP adapter configuration
<config name="dev3"> <target>dev3</target> <userName>abc</userName> <password>pass</password> <allow-unknown-hosts>true</allow-unknown-hosts> </config> <config name="dev4"> <target>dev4</target> <userName>asd</userName> <password>pass</password> <allow-unknown-hosts>true</allow-unknown-hosts> </config>

Figure 175 shows an XML sample of the adapter configuration for the SFTP adapter with the CharSet element. Figure 175 XML template of the SFTP adapter configuration
<config> <target>Server</target> <user-name>user</user-name> <password encryption-type="plain">pass</password> <timeout-secs>120</timeout-secs> <allow-unknown-hosts>true</allow-unknown-hosts> <character-set>Shift_JIS</character-set> </config>

220

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request

SFTP adapter request

The SFTP adapter uses the commands listed in Table 73 on page 221 as tag names in the request. The SFTP adapter does not use any actions. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. The sample requests and responses are provided for each of the commands available for this adapter. These samples are basic and do not reflect all the available features for this adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. The SFTP adapter supports the following commands: Table 73
Command cd chgrp chmod chown get get-dir lcd lpwd ls mkdir mkdirs put put-dir pwd rename rm symlink

SFTP adapter commands

Description Changes the directory on the remote server Changes the group for a specified file Changes the permissions for a specified file Changes the owner for a specified file Obtains a file from the remote server and places it on the local server Obtains the contents of a specified directory from a remote server Changes the directory on the local server Prints the working directory on the local server Lists the files on the remote server Creates a directory in an existing directory path on the remote server Creates a single or many directories in the path that does not currently exist on the remote server Transfers a file from the local server to the remote server Transfers the contents of a specified directory to the remote server Prints the working directory on the remote server Changes the name of a file on the remote server Deletes a specified file from the remote server Creates a symbolic link on the remote server for a specified file

Chapter 3

Using Terminal adapters

221

SFTP adapter request with cd command

SFTP adapter request with cd command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. Table 74 describes the adapter request elements for the SFTP adapter with cd command. Table 74
Element <targets>

Adapter request elementsSFTP adapter with cd command (part 1 of 2)

Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. If this value is not provided, the default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target computer Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. You can use the <private-key-file> element in the dynamic target

Conditional

Conditional

222

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with cd command

Table 74
Element

Adapter request elementsSFTP adapter with cd command (part 2 of 2)

Description Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds Required No

<timeoutsecs>

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target computer. Default value: homeDir/.ssh/known_hosts

Conditional

<allowunknownhosts>

Determines whether a connection must continue if the key verification fails This element applies to a dynamic target computer Valid values: true, false Default value: true

Conditional

Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error <preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target computer Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <cd> Contains the SFTP command element Indicates the directory the remote host must use as the working directory A directory must be specified for this element No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters Yes Yes No No Conditional

Chapter 3

Using Terminal adapters

223

SFTP adapter request with cd command

Figure 176 shows an XML template of the adapter request for the SFTP command with cd command. Figure 176 XML template of the SFTP adapter request with cd command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <cd></cd> </commands> </sftp-request>

Figure 177 shows an XML sample of the adapter request for the SFTP adapter with cd command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 177 XML sample of the SFTP adapter request with cd command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <cd>/tmp</cd> </commands> </sftp-request>

224

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with cd command

SFTP adapter response with cd command

The cd command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 75 describes the elements of an SFTP response to a request with cd command. Table 75
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with cd command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target computer The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

225

SFTP adapter request with chgrp command

Table 75
Element <error>

Elements of an SFTP adapter response to a request with cd command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains any lines that result from the command This command does not return a detailed response.

Figure 178 illustrates the adapter response for the SFTP adapter with cd command. Figure 178 XML sample of the SFTP adapter response with cd command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>cd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> /metadata> <output/> </command-output> </commands-output> </target-output> /targets-output> </sftp-command-output>>

SFTP adapter request with chgrp command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

226

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chgrp command

Table 76 describes the adapter request elements for the SFTP adapter with chgrp command. Table 76
Element <targets>

Adapter request elements for the SFTP adapter with chgrp command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request The default target in the adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target computer. <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target. You can use the <private-keyfile> element in the dynamic target <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

Conditional

No

Conditional

Chapter 3

Using Terminal adapters

227

SFTP adapter request with chgrp command

Table 76
Element <allowunknownhosts>

Adapter request elements for the SFTP adapter with chgrp command (part 2 of 2)
Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target. Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target. Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <chgrp> Contains the SFTP command and supporting elements Indicates the file's group is changed It also contains the elements defining the file and its new group <file> Specifies the remote file path, including the file name The group on this file is changed <gid> Specifies the group ID that is assigned to the specified file

Conditional

No

No

Yes Yes

Yes

Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

228

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chgrp command

Figure 179 shows an XML template of the adapter request for the SFTP adapter with the chgrp command. Figure 179 XML template of the SFTP adapter request with chgrp command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <chgrp> <file></file> <gid></gid> </chgrp> </commands> </sftp-request>

Figure 180 shows an XML sample of the adapter request for the SFTP adapter with chgrp command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 180 XML sample of the SFTP adapter request with chgrp command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <chgrp> <file>/path/to/file/filename</file> <gid>1</gid> </chgrp> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

229

SFTP adapter response with chgrp command

SFTP adapter response with chgrp command

The chgrp command request for a SFTP adapter returns an adapter response that contains the summary information for the command. Table 77 describes the elements of an SFTP adapter response to a request with chgrp command. Table 77
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with chgrp command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the <status> value is success, this element is absent.

<targets-output> <target-output>

Contains the command output for all target computers Contains the command output for a specific target computer The host attribute provides the host name or the IP address of the target computer.

<target-metadata> Contains the target level summary information <status> Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commands-output> Contains the command responses for all the commands executed on the target computer <command-output> <metadata> <id> <command> <executionmilliseconds> <status> Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

230

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chmod command

Table 77
Element <error>

Elements of an SFTP adapter response to a request with chgrp command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 181 shows an XML sample of the adapter request for the SFTP adapter with the chgrp command. Figure 181 XML sample of the SFTP adapter response with chgrp command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>chgrp</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with chmod command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. Table 78 describes the adapter request elements of the SFTP adapter with the chmod command.

Chapter 3

Using Terminal adapters

231

SFTP adapter request with chmod command

Table 78
Element

Adapter request elements of the SFTP adapter with chmod command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<targets>

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. The default target in the adapter configuration is used.

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target You can use the <private-key-file> element in the dynamic target <timeoutsecs>

Conditional

Conditional

Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target computer Default value: homeDdir/.ssh/known_hosts

Conditional

<allowunknownhosts>

Determines whether a connection must continue if key verification fails This element applies to a dynamic target computer Valid values: true (default), false

Conditional

Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error

232

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chmod command

Table 78
Element

Adapter request elements of the SFTP adapter with chmod command (part 2 of 2)
Description Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target computer. Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf the authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <chmod> Contains the SFTP command and supporting elements Indicates whether the file's permissions is changed It also contains the elements defining the file and its new permissions. <file> Specifies the remote file path, including the file name The permissions on this file is changed <permission Specifies the permission assigned to the specified file s>

No

No

Yes Yes

Yes

Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

Chapter 3

Using Terminal adapters

233

SFTP adapter request with chmod command

Figure 182 shows an XML template of the adapter request for the SFTP adapter with the chmod command. Figure 182 XML template of the SFTP adapter request with chmod command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <chmod> <file></file> <permissions></permissions> </chmod> </commands> </sftp-request>

Figure 183 shows an XML sample of the adapter request for the SFTP adapter with chmod command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 183 XML sample of the SFTP adapter request with chmod command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <chmod> <file>/path/to/file/filename</file> <permissions>0777</permissions> </chmod> </commands> </sftp-request>

234

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with chmod command

SFTP adapter response with chmod command

The chmod command request for the SFTP adapter returns an adapter response that contains the summary information for the command. Figure 184 shows an XML sample of the adapter request for the SFTP adapter with the chmod command. Figure 184 XML sample of the SFTP adapter response with chmod command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>chmod</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

Table 79 describes the elements of an SFTP adapter response to a request with chmod command. Table 79
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with chmod command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput>

Contains the command output for all the targets

Chapter 3

Using Terminal adapters

235

SFTP adapter request with chown command

Table 79
Element <targetoutput>

Elements of an SFTP adapter response to a request with chmod command (part 2 of 2)

Description Contains the command output for a specific target The host attribute provides the host name or the IP address of the target.

<targetmetadata> <status>

Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed

<executionSpecifies the duration of the command execution, in milliseconds milliseconds> <status> Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> Contains the lines that result from the command This command does not return a detailed response.

SFTP adapter request with chown command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target computer by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

236

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chown command

Table 80 describes the adapter request elements for the SFTP adapter with the chown command. Table 80
Element <targets>

Adapter request elements of the SFTP adapter with chown command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Conditional Contains a name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. The default target in the adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target This element is required when defining a dynamic target\. <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target You can use the <private-key-file> in the dynamic target <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target computer Default value: homeDir/.ssh/known_hosts

Conditional

Conditional

No

Conditional

Chapter 3

Using Terminal adapters

237

SFTP adapter request with chown command

Table 80
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with chown command (part 2 of 2)
Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target. Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf the authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <chown> Contains the SFTP command and supporting elements Indicates the file's owner is changed It also contains the elements defining the file and its new owner <file> The remote file path, including the file name The owner of this file is changed <uid> The user ID assigned to the specified file

Conditional

No

No

Yes Yes

Yes

Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

238

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with chown command

Figure 185 shows an XML template of the adapter request for the SFTP adapter with the chown command. Figure 185 XML template of the SFTP adapter request with chown command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <chown> <file></file> <uid></uid> </chown> </commands> </sftp-request>

Figure 186 shows an XML sample of the adapter request for the SFTP adapter with the chown command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 186 XML sample of the SFTP adapter request with chown command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <chown> <file>/path/to/file/filename</file> <uid>104</uid> </chown> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

239

SFTP adapter response with chown command

SFTP adapter response with chown command

The chown command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 81 describes the elements of an SFTP adapter response to a request with chown command. Table 81
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with chown command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

240

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with get command

Table 81
Element <error>

Elements of an SFTP adapter response to a request with chown command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output>

Contains any lines that result from the command This command does not return a detailed response.

Figure 187 illustrates an XML sample of the adapter response for the SFTP adapter with the chown command. Figure 187 XML sample of the SFTP adapter response with chown command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>chown</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with get command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. Table 82 describes the adapter request elements for the SFTP adapter with the get command.

Chapter 3

Using Terminal adapters

241

SFTP adapter request with get command

Table 82
Element

Adapter request elements of the SFTP adapter with get command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<targets>

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer By default, the default target in the adapter configuration is used This element is required if a target is referenced or defined in the request

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target port Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target computer <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. You can use the <private-key-file> element in the dynamic target. <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts <allowunknownhosts Determines whether a connection must continue if key verification fails This element applies to a dynamic target. Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error

Conditional

Conditional

No

Conditional

Conditional

242

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with get command

Table 82
Element

Adapter request elements of the SFTP adapter with get command (part 2 of 2)
Description Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target. Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliances. Valid values: true, false (default) <commands> <get> Contains the SFTP command and supporting elements Indicates a get function is performed It also contains the elements defining the local and remote files that are affected. <localfile> Specifies the local file path, including the file name This is the destination file for the get command. The path provided for the remote file is used. This path must correspond to a valid path on the local server to be successful. <remotefile> Specifies the remote file path, including the file name This is the source file for the get command.

No

No

Yes Yes

No

Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Chapter 3

Using Terminal adapters

243

SFTP adapter request with get command

Figure 188 shows an XML template of the adapter request for the SFTP adapter with the get command. Figure 188 XML template of the SFTP adapter request with get command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <get> <local-file></local-file> <remote-file></remote-file> </get> </commands> </sftp-request>

Figure 189 shows an XML sample of the adapter request for the SFTP adapter with the get command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 189 XML sample of the SFTP adapter request with get command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <get> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </get> </commands> </sftp-request>

244

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with get command

SFTP adapter response with get command

The get command request for the SFTP adapter returns an adapter response that contains the summary information for the command. Table 83 describes the elements of an SFTP adapter response to a request with get command. Table 83
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with get command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information. Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

245

SFTP adapter request with get-dir command

Table 83
Element <error>

Elements of an SFTP adapter response to a request with get command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent. If the transfer is interrupted, a partial file might exist in the destination location.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 190 illustrates an XML sample of the adapter response for the SFTP adapter with the get command. Figure 190 XML sample of the SFTP adapter response with get command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>get</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with get-dir command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

246

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with get-dir command

Table 84 describes the adapter request elements for the SFTP adapter with the get-dir command. Table 84
Element <targets>

Adapter request elements of the SFTP adapter with get-dir command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Contains the name attribute that references a configuration node from the Conditional adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request The default target in the adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name>

Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target

Conditional

<password>

Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target You can use the <private-key-file> element in the dynamic target

Conditional

<timeoutsecs>

Specifies the time, in seconds, to wait for the expected prompt to be returned If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

No

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

Chapter 3

Using Terminal adapters

247

SFTP adapter request with get-dir command

Table 84
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with get-dir command (part 2 of 2)
Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferredpkalgorithm>

Specifies the preference of the algorithm used to encrypt the public key This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default)

Conditional

<establishconnectiontimeoutsecs>

Specifies the time, in seconds, to wait for user authentication on the target No server If the authentication is not successful within this time, an error message is returned. Default value: 60 seconds

<networkCreates an extra channel session for use with Sun Solaris 9 environment> This value must be false when connecting to network appliances. Valid values: true, false (default) <commands> <get-dir> Contains the SFTP command and supporting elements Indicates whether the get directory function is performed It also contains the elements defining the local and remote directories that are affected. <local-dir> Specifies the local directory path This is the destination directory for the get-dir command. <remote-dir> Specifies the remote directory This is the source directory for the get-dir command. <characterset> Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters.

No

Yes Yes

Yes

Yes

No

248

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with get-dir command

Figure 191 shows an XML sample of the adapter request for the SFTP adapter with the get-dir command. Figure 191 XML sample of the SFTP adapter request with get-dir command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <get-dir> <local-dir></local-dir> <remote-dir></remote-dir> </get-dir> </commands> </sftp-request>

Figure 192 shows an XML sample of the adapter request for the SFTP adapter with the get-dir command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 192 XML sample of the SFTP adapter request with get-dir command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <get-dir> <local-dir>/path/to/directory</local-dir> <remote-dir>/path/to/directory</remote-dir> </get-dir> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

249

SFTP adapter response with get-dir command

SFTP adapter response with get-dir command

The get-dir command request for a SFTP adapter, returns an adapter response containing the summary information for the command. Table 85 describes elements of an SFTP adapter response to a request with get-dir command. Table 85
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with get-dir command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

250

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with lcd command

Table 85
Element <error>

Elements of an SFTP adapter response to a request with get-dir command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 193 illustrates an XML sample of the adapter response for the SFTP adapter with the get-dir command. Figure 193 XML sample of the SFTP adapter response with get-dir command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>get-dir</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with lcd command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

Chapter 3

Using Terminal adapters

251

SFTP adapter request with lcd command

Table 86 describes the adapter request elements for the SFTP adapter with the lcd command. Table 86
Element <targets>

Adapter request elements of the SFTP adapter with lcd command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request Default value: Default target in the adapter configuration

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target.

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target This element might be needed based on the requirements of the remote host <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target. The default is the <privatekey-file> element used in the dynamic target This element might be needed based on the requirements of the remote host. <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

Conditional

No

Conditional

252

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with lcd command

Table 86
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with lcd command (part 2 of 2)
Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <lcd> Contains the SFTP command element Indicates the directory the local host must use as the working directory A directory must be specified for this element

Conditional

No

No

Yes Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

Chapter 3

Using Terminal adapters

253

SFTP adapter request with lcd command

Figure 194 shows an XML template of the adapter request for the SFTP adapter with the lcd command. Figure 194 XML template for a SFTP adapter request with lcd command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <lcd></lcd> </commands> </sftp-request>

Figure 195 shows an XML sample of the adapter request for the SFTP adapter with the lcd command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 195 XML sample of the SFTP adapter request with lcd command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <lcd>/tmp</lcd> </commands> </sftp-request>

254

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with lcd command

SFTP adapter response with lcd command

The lcd command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 87 describes the elements of an SFTP adapter response to a request with lcd command. Table 87
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with Icd command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

255

SFTP adapter request with lpwd command

Table 87
Element <error>

Elements of an SFTP adapter response to a request with Icd command (part 2 of 2)

Description Contains the error message if a command level error occurs When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 196 illustrates an XML sample of the adapter response for the SFTP adapter with the lcd command. Figure 196 XML sample of the SFTP adapter response with lcd command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>lcd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with lpwd command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

256

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with lpwd command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 88 describes the adapter request elements for the SFTP adapter with the lpwd command. Table 88
Element <targets>

Adapter request elements of the SFTP adapter with Ipwd command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target. computer This element is required if a target is referenced or defined in the request Default value: Default target in the adapter configuration

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target computer <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer You can use the <private-key-file> element in the dynamic target computer <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

Conditional

No

Conditional

Chapter 3

Using Terminal adapters

257

SFTP adapter request with lpwd command

Table 88
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with Ipwd command (part 2 of 2)
Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target computer Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances. Valid values: true, false Default value: false <commands> <lpwd> Contains the SFTP command element

Conditional

No

No

Yes

Indicates the present working directory on the local server must be returned Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

258

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with lpwd command

Figure 197 shows an XML template of the adapter request for the SFTP adapter with the lpwd command. Figure 197 XML template of the SFTP adapter request with lpwd command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <lpwd/> </commands> </sftp-request>

Figure 198 shows an XML sample of the adapter request for the SFTP adapter with the lpwd command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 198 XML sample of the SFTP adapter request with lpwd command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <lpwd/> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

259

SFTP adapter response with lpwd command

SFTP adapter response with lpwd command

The lpwd command request for a SFTP adapter returns an adapter response that contains the present working directory on the local server. Table 89 describes the elements of an SFTP adapter response to a request with lpwd command. Table 89
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with lpwd command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

260

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with ls command

Table 89
Element <error>

Elements of an SFTP adapter response to a request with lpwd command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output> <lpwd>

Contains the lines that result from the command Indicates the present working directory on the local server

Figure 199 illustrates the adapter response for the SFTP adapter with lpwd command. Figure 199 XML sample of the SFTP adapter response with the lpwd command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>lpwd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <lpwd>/tmp</lpwd> </output> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with ls command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

Chapter 3

Using Terminal adapters

261

SFTP adapter request with ls command

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 90 describes the adapter request elements for the SFTP adapter with the ls command. Table 90
Element <targets>

Adapter request elements of the SFTP adapter with ls command (part 1 of 2)

Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request Default value: Default target in the adapter configuration

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target computer <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target The default is the <private-key-file> element <timeoutsecs>

Conditional

Conditional

Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

262

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with ls command

Table 90
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with ls command (part 2 of 2)

Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target. Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <ls Contains the SFTP command element Indicates the directory on the remote host for which files must be listed A directory must be specified in this element

Conditional

No

No

Yes Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

Chapter 3

Using Terminal adapters

263

SFTP adapter request with ls command

Figure 200 shows an XML sample of the adapter request for the SFTP adapter with the ls command. Figure 200 XML template of the SFTP adapter request with ls command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <ls></ls> </commands> </sftp-request>

Figure 201 shows an XML sample of the adapter request for the SFTP adapter with the ls command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 201 XML sample of the SFTP adapter request with ls command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <ls>/tmp</ls> </commands> </sftp-request>

264

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with ls command

SFTP adapter response with ls command

The ls command request for a SFTP adapter returns an adapter response containing the details about the files in the specified directory. Table 91 describes the elements of an SFTP adapter response to a request with ls command. Table 91
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with Is command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

265

SFTP adapter response with ls command

Table 91
Element <error>

Elements of an SFTP adapter response to a request with Is command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output> <file> <filename> <mask>

Contains any lines that result from the command Contains the detail lines returned for a file in the specified directory Indicates the file name Indicates the octal representation of the permissions for the file

<modification- Indicates the time of the last file modification time> <permissions> Indicates the file permissions This value consists of 10 characters, in 4 segments. The first segment is a single character that indicates the type, file (-), directory (d), symbolic link (s), or unknown (u). The next three segments are three characters each, representing the read (r), write (w), and execute (x) permissions on the file for the file owner, the group, and others. If no permission is granted, the permissions character is replaced with a hyphen (-) as a placeholder. Example: -rw-r--r-- indicates it is a file, with read and write permissions for the file owner, and read-only permissions for the group and others. <gid> <uid> Indicates the group ID of the file's group Indicates the user ID of the file's owner

266

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with mkdir command

Figure 202 illustrates the adapter response for the SFTP adapter with the ls command. Figure 202 XML template of the SFTP adapter request with ls command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>ls</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <file> <filename>Sample File1</name> <mask>0644</mask> <modification-time>Jan 01 01:00</modification-time> <permissions>-rw-r--r--</permissions> <gid>1</gid> <uid>106</uid> </file> <file> <filename>Sample File2</name> <mask>0600</mask> <modification-time>Jan 01 02:00</modification-time> <permissions>-rw-------</permissions> <gid>1</gid> <uid>106</uid> </file> </output> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with mkdir command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. In this sample, the first target references the adapter configuration and the second target is a dynamic target. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

Chapter 3

Using Terminal adapters

267

SFTP adapter request with mkdir command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 92 describes the adapter request elements for the SFTP adapter with the mkdir command. Table 92
Element <targets>

Adapter request elements of the SFTP adapter with mkdir command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request. Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. The default value in the adapter configuration is used as the default target

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication. This element applies to a dynamic target and is when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target By default, you can use the <private-key-file> element in the dynamic target <timeoutsecs>

Conditional

Conditional

Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

268

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with mkdir command

Table 92
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with mkdir command (part 2 of 2)
Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection drops and the adapter response returns an error. Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <mkdir> Contains the SFTP command element Indicates the existing path on the remote server and the name of the directory to be created

Conditional

No

No

Yes Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

Figure 203 shows an XML template of the adapter request for the SFTP adapter with the mkdir command.

Chapter 3

Using Terminal adapters

269

SFTP adapter request with mkdir command

Figure 203 XML template of the SFTP adapter request with mkdir command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <mkdir></mkdir> </commands> </sftp-request>

Figure 204 shows an XML sample of the adapter request for the SFTP adapter with the mkdir command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 204 XML sample of the SFTP adapter request with mkdir command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <mkdir>/path/to/new/directory/directory name</mkdir> </commands> </sftp-request>

270

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with mkdir command

SFTP adapter response with mkdir command

The mkdir command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 93 describes the elements of an SFTP adapter response to a request with mkdir command. Table 93
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with mkdir command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the <status> value is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target. The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

271

SFTP adapter request with mkdirs command

Table 93
Element <error>

Elements of an SFTP adapter response to a request with mkdir command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 205 illustrates the adapter response for the SFTP adapter with the mkdir command. Figure 205 XML sample of the SFTP adapter response with mkdir command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>mkdir</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with mkdirs command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. If the target block is not supplied, the default target from the adapter configuration is used.

272

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with mkdirs command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 94 describes the adapter request elements for the SFTP adapter with the mkdirs command. Table 94
Element <targets>

Adapter request elements of the SFTP adapter with mkdirs command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. If a value is not supplied, the default target adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element is required if a dynamic target is used

Conditional

<port>

Specifies the port on which the remote host listens This element applies to a dynamic target Default port: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target. By default, you can use the <private-key-file> element in the dynamic target <timeoutsecs>

Conditional

Conditional

Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

Chapter 3

Using Terminal adapters

273

SFTP adapter request with mkdirs command

Table 94
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with mkdirs command (part 2 of 2)
Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection drops and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target computer. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned. Default value: 60 seconds <networkCreate an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances. Valid values: true, false Default value: false <commands> <mkdirs> Contains the SFTP command element Indicates the path on the remote server and the name of the directory to be created Any supporting directories that do not currently exist are created.

Conditional

No

No

Yes Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

274

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with mkdirs command

Figure 206 shows an XML template of the adapter request for the SFTP adapter with the mkdirs command. Figure 206 XML template of the SFTP adapter request with mkdirs command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <mkdirs></mkdirs> </commands> </sftp-request>

SFTP adapter response with mkdirs command

The mkdirs command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 95 describes the elements of an SFTP adapter response to a request with mkdirs command. Table 95
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with mkdirs command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput>

Contains the command output for all target computers Contains the command output for a specific target The host attribute provides the host name or the IP address of the target.

Chapter 3

Using Terminal adapters

275

SFTP adapter response with mkdirs command

Table 95
Element

Elements of an SFTP adapter response to a request with mkdirs command (part 2 of 2)

Description Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<targetmetadata> <status>

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed The command executed The duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output>

Contains any lines that result from the command This command does not return a detailed response.

276

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with put command

Figure 207 illustrates the adapter response for the SFTP adapter with the mkdirs command. Figure 207 XML sample of the SFTP adapter response with mkdirs command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>mkdirs</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with put command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 96 describes the adapter request elements for the SFTP adapter with the put command.

Chapter 3

Using Terminal adapters

277

SFTP adapter request with put command

Table 96
Element

Adapter request elements of the SFTP adapter with put command (part 1 of 2)
Description Contains the <target>elements This element is required if a target computer is referenced or defined in the request Required Conditional

<targets>

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target computer is referenced or defined in the request. If the element is not defined, the default target in the adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required when defining a dynamic target host

Conditional

<port>

Specifies the port on which the remote host listens If you do not provide the value, a default value of 22 is used

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. If not provided, you can use the <private-key-file> element in the dynamic target <timeoutsecs>

Conditional

Conditional

Specifies the time, in seconds, to wait for the expected prompt to be returned No If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds

<knownhostsconfig>

Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts

Conditional

<allowunknownhosts>

Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false

Conditional

Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error

278

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with put command

Table 96
Element

Adapter request elements of the SFTP adapter with put command (part 2 of 2)
Description Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <put Contains the SFTP command and supporting elements Indicates whether a put function is performed It also contains the elements defining the local and remote files that are affected <localfile> <remotefile> Specifies the local file path, including the file name This is the source file for the put command Specifies the remote file path, including the file name This is the destination file for the put command. If not provided, the path provided for the local file is used. This path must correspond to a valid path on the remote server to be successful

No

No

Yes Yes

Yes

No

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Figure 208 shows an XML template of the adapter request for the SFTP adapter with the put command.

Chapter 3

Using Terminal adapters

279

SFTP adapter request with put command

Figure 208 XML template of the SFTP adapter request with put command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <put> <local-file></local-file> <remote-file></remote-file> </put> </commands> </sftp-request>

Figure 209 shows an XML sample of the adapter request for the SFTP adapter with the put command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 209 XML sample of the SFTP adapter request with put command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <put> <local-file>/path/to/file/filename</local-file> <remote-file>/path/to/file/filename</remote-file> </put> </commands> </sftp-request>

280

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with put command

SFTP adapter response with put command

The put command request for a SFTP adapter returns an adapter response containing the summary information for the command. Table 97 describes the elements of an SFTP adapter response to a request with put command. Table 97
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with put command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> status>

Contains the command output for all the targets Contains the command output for a specific target computer The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

commandsoutput> commandoutput> metadata> id> command> executionmilliseconds> status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

281

SFTP adapter request with put-dir command

Table 97
Element error>

Elements of an SFTP adapter response to a request with put command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. If the transfer is interrupted, a partial file might exist in the destination location.

output>

Contains any lines that result from the command This command does not return a detailed response.

Figure 210 illustrates an XML sample of the adapter response for the SFTP adapter with the put command. Figure 210 XML sample of the SFTP adapter response with put command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>put</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with put-dir command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.
282 BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with put-dir command

Table 98 describes the adapter request elements for the SFTP adapter with the put-dir command. Table 98
Element <targets>

Adapter request elements of the SFTP adapter with put-dir command (part 1 of 2)
Description Contains the <target> elements This element is required if a target is referenced or defined in the request Required Conditional

<target>

Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used

<host>

Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target. This element applies to a dynamic target computer.

Conditional

<port>

Specifies the port on which the remote host listens Default value: 22

Conditional

<user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target computer <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. If you do not provide the value, you can use the <private-key-file> element in the dynamic target. <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target computer Default value: homeDir/.ssh/known_hosts

Conditional

Conditional

No

Conditional

Chapter 3

Using Terminal adapters

283

SFTP adapter request with put-dir command

Table 98
Element <allowunknownhosts>

Adapter request elements of the SFTP adapter with put-dir command (part 2 of 2)
Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error Required Conditional

<preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliance Valid values: true, false (default) <commands> <put-dir> Contains the SFTP command and supporting elements Indicates whether the put directory function is performed It also contains the elements defining the local and remote directories that is affected <local-dir> Specifies the local directory path. This is the source directory for the put-dir command <remotedir> Specifies the remote directory This is the destination directory for the put-dir command.

Conditional

No

No

Yes Yes

Yes

Yes

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters.

Figure 211 shows an XML template of the adapter request for the SFTP adapter with the put-dir command.

284

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with put-dir command

Figure 211 XML template of the SFTP adapter request with put-dir command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set></character-set> </target> </targets> <commands> <put-dir> <local-dir></local-dir> <remote-dir></remote-dir> </put-dir> </commands> </sftp-request>

Figure 212 shows an XML sample of the adapter request for the SFTP adapter with the put-dir command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 212 XML sample of the SFTP adapter request with put-dir command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <put-dir> <local-dir>/path/to/directory</local-dir> <remote-dir>/path/to/directory</remote-dir> </put-dir> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

285

SFTP adapter response with put-dir command

SFTP adapter response with put-dir command

The put-dir command request for the SFTP adapter returns an adapter response containing the summary information for the command. Table 99 describes the elements of an SFTP adapter response to a request with put-dir command. Table 99
Element <requestmetadata> <status>

Elements of an SFTP adapter response to a request with put-dir command (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <status>

Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target host. Contains the target level summary information Indicates the status of the target connection Valid values: success, error

<error>

Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

286

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with pwd command

Table 99
Element <error>

Elements of an SFTP adapter response to a request with put-dir command (part 2 of 2)

Description Contains the error message if the execution of a command is interrupted When value of the <status> element is success, this element is absent.

<output>

Contains the lines that result from the command This command does not return a detailed response.

Figure 213 illustrates the adapter response for the SFTP adapter with the put-dir command. Figure 213 XML sample of the SFTP adapter response with put-dir command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>put-dir</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with pwd command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

Chapter 3

Using Terminal adapters

287

SFTP adapter request with pwd command

Table 100 describes the adapter request elements for the SFTP adapter with the pwd command. Table 100 Adapter request elements for the SFTP adapter with pwd command (part 1 of 2)
Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used. <host> Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target. <port> Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22 <user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. If you do not provide the value, you can use the <private-key-file> element in the dynamic target computer <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts Conditional No Conditional Conditional Conditional Conditional Required Conditional

288

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with pwd command

Table 100 Adapter request elements for the SFTP adapter with pwd command (part 2 of 2)
Element <allowunknownhosts> Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target. Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error <preferredpkalgorithm> Specifies the preference of the algorithm used to encrypt the public key This element applies to a dynamic target computer. Valid values: ssh-dss, ssh-rsa (default) <establishconnectiontimeoutsecs> Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment> This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <pwd <characterset> Contains the SFTP command element Displays the present working directory of the remote server Specifies the supporting CharSet CharSet is also called Character set that are identifiers describing a series of universal characters Yes Yes No No No Conditional Required Conditional

Chapter 3

Using Terminal adapters

289

SFTP adapter request with pwd command

Figure 215 shows an XML template of the adapter request for the SFTP adapter with the pwd command. Figure 214 XML template of the SFTP adapter request with pwd command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <pwd/> </commands> </sftp-request>

Figure 215 shows an XML sample of the adapter request for the SFTP adapter with the pwd command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 215 XML sample of the SFTP adapter request with pwd command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <pwd/> </commands> </sftp-request>

290

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with pwd command

SFTP adapter response with pwd command

The pwd command request for a SFTP adapter returns an adapter response containing the present working directory on the remote server. Table 101 describes the elements of an SFTP adapter response to a request with pwd command. Table 101 Elements of an SFTP adapter response to a request with pwd command (part 1 of 2)
Element <requestmetadata> <status> Description Contains the request level summary information Indicates the status of the request Valid values: success, error <error> Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent. <targetsoutput> <targetoutput> <targetmetadata> <status> Contains the command output for all the targets Contains the command output for a specific target The host attribute provides the host name or the IP address of the target. Contains the target level summary information Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element success, this element is absent. <commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status> Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

Chapter 3

Using Terminal adapters

291

SFTP adapter request with rename command

Table 101 Elements of an SFTP adapter response to a request with pwd command (part 2 of 2)
Element <error> Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> <pwd> Contains the lines that result from the command Indicates the present working directory on the remote server

Figure 216 illustrates the adapter response for the SFTP adapter with the pwd command. Figure 216 XML sample of the SFTP adapter response with pwd command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>pwd</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output> <pwd>/tmp</pwd> </output> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with rename command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

292

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with rename command

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 102 describes the adapter request elements for the SFTP adapter with the rename command. Table 102 Adapter request elements of the SFTP adapter with rename command (part 1 of 2)
Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request If you do not provide the value, the default target in the adapter configuration is used <host> Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer <port> Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22 <user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target and is required when defining a dynamic target computer <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. If you do not provide the value, you can use the <private-key-file> element in the dynamic target computer <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts Conditional No Conditional Conditional Conditional Conditional Required Conditional

Chapter 3

Using Terminal adapters

293

SFTP adapter request with rename command

Table 102 Adapter request elements of the SFTP adapter with rename command (part 2 of 2)
Element <allowunknownhosts> Description Determines whether a connection must continue if the key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error <preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target. Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliances. Valid values: true, false (default) <commands> <rename> Contains the SFTP command and supporting elements Indicates whether a file is renamed It also contains the elements defining the existing and new file names <old-file> Specifies the remote file path, including the file name of the existing file This file is renamed new-file> Specifies the remote file path, including the new file name Yes No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters Yes Yes Yes No No Conditional Required Conditional

Figure 217 shows an XML template of the adapter request for the SFTP adapter with the rename command.

294

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with rename command

Figure 217 XML template of the SFTP adapter request with rename command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <rename> <old-file></old-file> <new-file></new-file> </rename> </commands> </sftp-request>

In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 218 XML sample of the SFTP adapter request with rename command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <rename> <old-file>/path/to/file/filename</old-file> <new-file>/path/to/file/new filename</new-file> </rename> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

295

SFTP adapter response with rename command

SFTP adapter response with rename command

The rename command request for a SFTP adapter returns an adapter response that contains the summary information for the command. Table 103 describes the elements of an SFTP adapter response to a request with rename command. Table 103 Elements of an SFTP adapter response to a request with rename command (part 1 of 2)
Element <requestmetadata> <status> Description Contains the request level summary information Indicates the status of the request Valid values: success, error <error> Indicates the error message returned when the value of the <status> element is error When value of the <status> element is success, this element is absent. <targetsoutput> <targetoutput> <targetmetadata> <status> Contains the command output for all target computers Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commandsoutput> commandoutput> <metadata> <id> <command> <executionmilliseconds> <status> Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

296

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with rm command

Table 103 Elements of an SFTP adapter response to a request with rename command (part 2 of 2)
Element <error> Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> Contains the lines that result from the command This command does not return a detailed response.

Figure 219 shows an XML sample of the adapter response for the SFTP adapter with the rename command. Figure 219 XML sample of the SFTP adapter response with rename command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>rename</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with rm command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

Chapter 3

Using Terminal adapters

297

SFTP adapter request with rm command

Table 104 describes the adapter request elements for the SFTP adapter with the rm command. Table 104 Adapter request elements for the SFTP adapter with rm command (part 1 of 2)
Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used. <host> Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target computer <port> Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 22 <user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target. If you do not provide the value, you can use the <private-key-file> element in the dynamic target. <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhosts>config Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts Conditional No Conditional Conditional Conditional Conditional Required Conditional

298

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with rm command

Table 104 Adapter request elements for the SFTP adapter with rm command (part 2 of 2)
Element <allowunknownhosts> Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target computer. Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false the connection is dropped and the adapter response returns an error <preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds <networkCreates an extra channel session for use with Sun Solaris 9 environment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <rm> Contains the SFTP command element Indicates the file name to be removed from the remote server Yes Yes No No Conditional Required Conditional

No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters

Chapter 3

Using Terminal adapters

299

SFTP adapter response with rm command

Figure 220 shows an XML template of the adapter request for the SFTP adapter with the rm command. Figure 220 XML template for a SFTP adapter request with rm command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <rm></rm> </commands> </sftp-request>s

Figure 221 shows an XML sample of the adapter request for the SFTP adapter with the rm command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 221 XML sample of the SFTP adapter request with rm command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <rm>filename</rm> </commands> </sftp-request>

SFTP adapter response with rm command

The rm command request for the SFTP adapter returns an adapter response that contains the summary information for the command.

300

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with rm command

Table 105 describes the elements of an SFTP adapter response to a request with the rm command. Table 105 Elements of an SFTP adapter response to a request with rm command
Element <requestmetadata> <status> Description Contains the request level summary information Indicates the status of the request Valid values: success, error <error> Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent. <targetsoutput> <targetoutput> <targetmetadata> <status> Contains the command output for all target computers Contains the command output for a specific target The host attribute provides the host name or the IP address of the target host. Contains the target level summary information Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status> Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error <error> Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> Contains the lines that result from the command This command does not return a detailed response.

Chapter 3

Using Terminal adapters

301

SFTP adapter request with symlink command

Figure 222 illustrates the adapter response for the SFTP adapter with the rm command. Figure 222 XML sample of the SFTP adapter response with rm command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>rm</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with symlink command

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors.

302

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with symlink command

Table 106 describes the adapter request elements for the SFTP adapter with the symlink command. Table 106 Adapter request elements of the SFTP adapter with symlink command (part 1 of 2)
Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used. <host> Specifies the host name or the IP address of the remote host This element is required when defining a dynamic target host. <port> Specifies the port on which the remote host listens This element applies to a dynamic target Default value: 23 <user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer and is required when defining a dynamic target <password> Specifies the password that corresponds to the <user-name> provided This element applies to a dynamic target computer. If you do not provide the value, you can use the <private-key-file> element in the dynamic target <timeoutsecs> Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds <knownhostsconfig> Identifies the path to the local known_hosts file This file is used when performing key verification This element applies to a dynamic target Default value: homeDir/.ssh/known_hosts Conditional No Conditional Conditional Conditional Conditional Required Conditional

Chapter 3

Using Terminal adapters

303

SFTP adapter request with symlink command

Table 106 Adapter request elements of the SFTP adapter with symlink command (part 2 of 2)
Element <allowunknownhosts> Description Determines whether a connection must continue if key verification fails This element applies to a dynamic target Valid values: true (default), false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. <preferred- Specifies the preference of the algorithm used to encrypt the public key pkalgorithm> This element applies to a dynamic target computer Valid values: ssh-dss, ssh-rsa (default) <establish- Specifies the time, in seconds, to wait for user authentication on the target connection- server. timeoutIf authentication is not successful within this time, an error message is secs> returned Default value: 60 seconds Creates an extra channel session for use with Sun Solaris 9 <networkenvironment > This value must be false when connecting to network appliances Valid values: true, false (default) <commands> <symlink> Contains the SFTP command and supporting elements Indicates a symbolic link is created It also contains the elements that define the file and the link name <file> Specifies the remote file path, including the file name of the existing file This file will have a symbolic link created <link> Specifies the name of the link for the specified file Yes No <character- Specifies the supporting CharSet set> CharSet is also called Character set that are identifiers describing a series of universal characters Yes Yes Yes No No Conditional Required Conditional

Figure 223 shows an XML template of the adapter request for the SFTP adapter with the symlink command.

304

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with symlink command

Figure 223 XML template of the SFTP adapter request with symlink command
<sftp-request> <targets> <target name=""/> <target> <host></host> <port></port> <user-name></user-name> <password></password> <timeout-secs></timeout-secs> <known-hosts-config></known-hosts-config> <allow-unknown-hosts></allow-unknown-hosts> <preferred-pk-algorithm></preferred-pk-algorithm> <establish-connection-timeout-secs></establish-connection-timeout-secs> <network-environment></network-environment> <character-set>Shift_JIS</character-set> </target> </targets> <commands> <symlink> <file></file> <link></link> </symlink> </commands> </sftp-request>

Figure 224 shows an XML sample of the adapter request for the SFTP adapter with the symlink command. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 224 XML sample of the SFTP adapter request with symlink command
<sftp-request> <targets> <target name="host1"/> <target> <host>server1</host> <port>2200</port> <user-name>user</user-name> <password>test</password> <timeout-secs>90</timeout-secs> <known-hosts-config>/path/to/known_hosts</known-hosts-config> <allow-unknown-hosts>false</allow-unknown-hosts> <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm> <establish-connection-timeout-secs>90</establish-connection-timeout-secs> <network-environment>true</network-environment> </target> </targets> <commands> <symlink> <file>/path/to/file/filename</file> <link>link name</link> </symlink> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

305

SFTP adapter response with symlink command

SFTP adapter response with symlink command

The symlink command request for the SFTP adapter returns an adapter response that contains the summary information for the command. Table 107 describes the elements of an SFTP adapter response to a request with the symlink command. Table 107 Elements of an SFTP adapter response to a request with symlink command (part 1 of 2)
Element <requestmetadata> <status> Description Contains the request level summary information Indicates the status of the request Valid values: success, error <error> Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent. <targetsoutput> <targetoutput> <targetmetadata> <status> Contains the command output for all target computers Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the status of the target connection Valid values: success, error <error> Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent. <commandsoutput> <commandoutput> <metadata> <id> <command> <executionmilliseconds> <status> Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the sequence in which the command is executed Specifies the command executed Specifies the duration of the command execution, in milliseconds Indicates the status of the command execution Valid values: success, error

306

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter request with multiple commands

Table 107 Elements of an SFTP adapter response to a request with symlink command (part 2 of 2)
Element <error> Description Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent. <output> Contains the lines that result from the command This command does not return a detailed response.

Figure 225 illustrates an XML sample of the adapter response for the SFTP adapter withe the symlink command. Figure 225 XML sample of the SFTP adapter response with symlink command
<sftp-command-output> <request-metadata> <status>success</status> <error>Present only with status of 'error'</error> </request-metadata> <targets-output> <target-output host="server1"> <target-metadata> <status>success</status> <error>Present only with status of 'error'</error> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>symlink</command> <execution-milliseconds>value</execution-milliseconds> <status>success</status> <error>Present only with status of 'error'</error> </metadata> <output/> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

SFTP adapter request with multiple commands

Figure 226 shows an XML sample of the adapter request for the SFTP adapter with multiple commands. Figure 226 XML sample of the SFTP adapter request with multiple commands
<sftp-request> <commands> <cd>/export/home/smiley</cd> <ls>/export/home/smiley</ls> </commands> </sftp-request>

Chapter 3

Using Terminal adapters

307

SFTP adapter response with multiple commands

SFTP adapter response with multiple commands

Figure 227 shows an XML sample of the adapter response for the SFTP adapter with multiple commands.

308

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with multiple commands

Figure 227 XML sample of the SFTP adapter response with multiple commands (part 1 of 3)
<sftp-command-output> <response-metadata> <status>success</status> </response-metadata> <targets-output> <target-output host="10.128.248.114"> <target-metadata> <status>success</status> </target-metadata> <commands-output> <command-output> <metadata> <id>1</id> <command>cd</command> <execution-milliseconds>5</execution-milliseconds> <status>success</status> </metadata> <output /> </command-output> <command-output> <metadata> <id>2</id> <command>ls</command> <execution-milliseconds>22</execution-milliseconds> <status>success</status> </metadata> <output> <file> <filename>.</filename> <mask>0774</mask> <modification-time>1273669400</modification-time> <permissions>drwxrwxr--</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>..</filename> <mask>0755</mask> <modification-time>1271151374</modification-time> <permissions>drwxr-xr-x</permissions> <gid>0</gid> <uid>0</uid> </file> <file> <filename>build</filename> <mask>0777</mask> <modification-time>1273661391</modification-time> <permissions>drwxrwxrwx</permissions> <gid>0</gid> <uid>0</uid> </file> <file> <filename>upgradeCDP</filename> <mask>0775</mask> <modification-time>1273746424</modification-time> <permissions>drwxrwxr-x</permissions> <gid>0</gid> <uid>0</uid> </file> <file> <filename>AP</filename> <mask>0775</mask> <modification-time>1272885148</modification-time> <permissions>drwxrwxr-x</permissions> <gid>0</gid> <uid>0</uid> </file>

Chapter 3

Using Terminal adapters

309

SFTP adapter response with multiple commands

Figure 228 XML sample of the SFTP adapter response with multiple commands (part 2 of 3)
<file> <filename>.bash_history</filename> <mask>0600</mask> <modification-time>1270709978</modification-time> <permissions>-rw-------</permissions> <gid>0</gid> <uid>0</uid> </file> <file> <filename>.profile</filename> <mask>0664</mask> <modification-time>1233998210</modification-time> <permissions>-rw-rw-r--</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.ssh</filename> <mask>0700</mask> <modification-time>1204557909</modification-time> <permissions>drwx------</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.bmc_profile</filename> <mask>0775</mask> <modification-time>1256711323</modification-time> <permissions>-rwxrwxr-x</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.Xauthority</filename> <mask>0600</mask> <modification-time>1261388411</modification-time> <permissions>-rw-------</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.dt</filename> <mask>0755</mask> <modification-time>1261388415</modification-time> <permissions>drwxr-xr-x</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.cshrc</filename> <mask>0664</mask> <modification-time>1233998214</modification-time> <permissions>-rw-rw-r--</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.InstallAnywhere</filename> <mask>0775</mask> <modification-time>1256551627</modification-time> <permissions>drwxrwxr-x</permissions> <gid>1</gid> <uid>1055</uid> </file>

310

BMC Atrium Orchestrator Base Adapters User Guide

SFTP adapter response with multiple commands

Figure 229 XML sample of the SFTP adapter response with multiple commands (part 3 of 3)
<file> <filename>.TTauthority</filename> <mask>0600</mask> <modification-time>1261388412</modification-time> <permissions>-rw-------</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>upgradedCDP1</filename> <mask>0755</mask> <modification-time>1273669410</modification-time> <permissions>drwxr-xr-x</permissions> <gid>0</gid> <uid>0</uid> </file> <file> <filename>.dtprofile</filename> <mask>0755</mask> <modification-time>1226653961</modification-time> <permissions>-rwxr-xr-x</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.softwareupdate</filename> <mask>0755</mask> <modification-time>1226653982</modification-time> <permissions>drwxr-xr-x</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>.bmc_cshrc</filename> <mask>0775</mask> <modification-time>1256711325</modification-time> <permissions>-rwxrwxr-x</permissions> <gid>1</gid> <uid>1055</uid> </file> <file> <filename>adapter_options.txt</filename> <mask>0644</mask> <modification-time>1273665027</modification-time> <permissions>-rw-r--r--</permissions> <gid>0</gid> <uid>0</uid> </file> </output> </command-output> </commands-output> </target-output> </targets-output> </sftp-command-output>

Chapter 3

Using Terminal adapters

311

Windows Command adapter

Windows Command adapter

The Windows Command adapter is used to execute commands on a remote host running the Windows operating system. The Windows Command adapter can use the following common features. For details about terminal adapter features, see Terminal adapter features on page 23.
s s

s s s

Command Attributes: working-dir, command-dir, timeout-secs FAT CommandsCommand attributes: encryption-type disable-line-termination is-special-character os-id os-version Password Attribute: encryption-type Multiple Configuration nodes Dynamic Targets

The Windows Command adapter uses a utility, xCmd, to execute a Windows command on a remote host. The utility then returns the results to the user. The Windows Command adapter does not utilize the xCmd utility in the following cases:
s

When you specify an empty configuration and you do not specify a dynamic target in the adapter request When you do not specify a host in the <target> block of the adapter configuration or the <host> tag in the dynamic target request

If you specify 127.0.0.1 or the host name of the local computer, the adapter uses the xCmd utility for executing the commands. This section describes the configuration, request format, and response format of the Windows Command adapter:

Windows Command adapter postinstallation steps Windows Command adapter request

Windows Command adapter configuration Windows Command adapter response

312

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter post-installation steps

Windows Command adapter post-installation steps

You can enable the Windows Command adapter on BMC Atrium Orchestrator peers running on a Microsoft Windows XP, Microsoft Windows Server 2003, or Microsoft Windows Server 2008 operating system. In addition to enabling the adapter on a Windows peer, you must adjust the permission levels for the BMC Atrium Orchestrator service on that peer to allow the adapter to communicate properly.

Before you begin

Set the permissions for the Windows Command adapter when the adapter is in the default mode.

To set permissions for the Windows Command adapter

1 On the peer on which the Windows Command adapter is enabled, navigate to the
Services window (Start => Control Panel => Administrative Tools => Services).

2 From the Services page, right-click the BMC Atrium Orchestrator AP, BMC Atrium
Orchestrator LAP, BMC Atrium Orchestrator CDP, or BMC Atrium Orchestrator HACDP service, and select Properties from the pop-up menu.

3 Click the Log On tab, and then click the This account option. 4 Type the username to be used for this service and the corresponding password for
the user.

NOTE
The user must be able to communicate externally and use a communication interface.

5 Click Apply, and then click OK. 6 Restart the BMC Atrium Orchestrator AP, BMC Atrium Orchestrator LAP, BMC Atrium
Orchestrator CDP, or BMC Atrium Orchestrator HACDP service.

Chapter 3

Using Terminal adapters

313

Windows Command adapter configuration

Windows Command adapter configuration

In addition to targets defined in the adapter configuration, the Windows Command adapter can have dynamic targets defined in each adapter request. If a dynamic target will always be defined in the Windows Command adapter request, a configuration node of <config/> can be used in the adapter configuration. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. The remote service starts once you provide the credentials in the adapter configuration or request depending on the access rights. The Windows Command adapter configuration supports the SSH functionality along with the xCmd utility. With the SSH functionality, a non-administrator user can execute commands on the remote computer if the SSH server is installed and running on the target computer.

NOTE
The default port for SSH is 22.

Adapter type: ro-adapter-windows-command[version] Default adapter name: WindowsCommandAdapter To configure the Windows Command adapter, see Configuring the adapter on page 14. Table 108 describes the adapter configuration elements for the Windows Command adapter that you can specify by 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. Table 108 Adapter configuration elements for the Windows Command adapter (part 1 of 3)
UI label Target Element <config> <target> Description Contains the elements for the adapter configuration Specifies the host name or the IP address of the remote host Default value: localhost Required No No

314

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter configuration

Table 108 Adapter configuration elements for the Windows Command adapter (part 2 of 3)
UI label User Name Element <user-name> Description Specifies the user name to be used for remote host authentication The requirements of the user's environment determine whether the <user-name> element is required. This user must have an administrator role and privileges on the remote host. Password <password> Conditional Specifies the password that corresponds to the <user-name> provided or that used for remote host authentication The requirements of the user's environment determine whether the <password> element is required. Logon With User Credentials No <logon-with- Starts a service on the remote computer usercredentials> If the value is true, the remote service is started using the credentials specified in the adapter configuration; else, the remote service is started using system credentials. Valid values: true, false (default) Executable Directory <executable- Specifies the complete path to the directory in which directory> the .exe is located This element is applicable in the default mode only Default value: $AO_HOME/server/<Grid>/library/adapters/roadapter-windows-command-version Executable <executable> Specifies the program to be used to execute the command This element is applicable in default mode only Default value: xCmd.exe Escape Double Quotes <escapedoublequotes> Escapes the double quotes (") by using a double backslash (\\) in the command This element is applicable in default mode only Valid values: true (default), false Protocol <protocol> Decides whether the command is routed through the xCmd utility or ssh Default value: xCmd No No No No Required Conditional

Chapter 3

Using Terminal adapters

315

Windows Command adapter configuration

Table 108 Adapter configuration elements for the Windows Command adapter (part 3 of 3)
UI label Element Description Specifies whether the path to the script file is relative to the local (peer) or the remote (target) computer. This element is applicable to the xCmd utility only. Valid values: local (default), remote Note:
s

Required No

Script File Path <scriptfile-path>

If the name of the script file has spaces, the script file name along with the path must be in double quotes ( ). A relative path must start with .\ (dot and back slash characters). Conditional

Max Request Queue Size

<maxrequestqueue-size> <debugutility>

Specifies the maximum size of the queue maintained by the adapter to handle concurrent requests Default value: 65535

Debug Utility

Specify whether xCmd run in debug mode or nondebug mode If the value is set to be true, the utility(xCmd) runs in debug mode. Valid values: true, false (default)

No

Figure 230 shows an XML template for the Windows command adapter configuration. Figure 230 XML template of the Windows command adapter configuration
<config> <target></target> <user-name></user-name> <password></password> <logon-with-user-credentials></logon-with-user-credentials> <protocol></protocol> <executable-directory></executable-directory> <executable></executable> <escape-double-quotes></escape-double-quotes> <protocol></protocol> <script-file-path></script-file-path> <max-request-queue-size></max-request-queue-size> <debug-utility></debug-utility> </config>

Figure 231 shows an XML sample for the adapter configuration for the Windows Command adapter using the xCmd utility.

316

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter request

Figure 231 XML sample of the Windows command adapter configuration using the xCmd utility
<config> <target>abc2</target> <user-name>Administrator</user-name> <password>test</password> <logon-with-user-credentials>true</logon-with-user-credentials> <protocol>default</protocol> <script-file-path>local</script-file-path> </config>

Figure 232 shows an XML sample for the adapter configuration for the Windows Command adapter using the ssh utility. Figure 232 XML sample of the Windows command adapter configuration using SSH
<config> <target>abc2</target> <user-name>Administrator</user-name> <password>test</password> <protocol>ssh</protocol> </config>

The Windows Command adapter supports the 64-bit Windows 2008 operating system. By default, the firewall is enabled on a 64-bit Windows 2008 computer, which disables the Internet Control Message Protocol (ICMP). If the adapter does not execute commands on the target computer after enabling the adapter (that supports a 64-bit Windows 2008 operating system), you must enable file sharing and the ICMP used by the xCmd.

To enable the ICMP on the target computer 1 Type netsh firewall set icmpsetting 8 enable on the Windows command line and
press Enter to enable the ICMP on the computer.

To enable file sharing 1 On the 64-bit Windows 2008 computer, navigate to Start => Network => Network
and Sharing centre.

2 On the Network and Sharing centre page, enable the File sharing option, and click
Save to enable file sharing.

Windows Command adapter request

The Windows Command adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 3

Using Terminal adapters

317

Windows Command adapter request

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target computer by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Table 109 describes the adapter request elements for the Windows Command adapter. Table 109 Adapter request elements of the Windows Command adapter
Element <targets> Description Contains the <target> elements This element is required if a target is referenced or defined in the request. <target> Conditional Contains the name attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer This element is required if a target is referenced or defined in the request. If you do not provide the value, the default target in the adapter configuration is used. <host> Specifies the host name or the IP address of the remote host This element applies to a dynamic target and is required when defining a dynamic target host. <user-name> Specifies the user name to be used for remote host authentication This element applies to a dynamic target computer. The requirements of the user's environment determine whether the <user-name> element is required. <password> Specifies the password that corresponds to the <user-name> provided or that used for remote host authentication This element applies to a dynamic target computer. The requirements of the user's environment determine whether the <password> element is required. <commands> <command> Contains the <command> elements Specifies the commands to be executed on the remote host Yes Yes Conditional Conditional Conditional Required Conditional

Figure 233 shows an XML template of the adapter request for the Windows Command adapter.

318

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter request

Figure 233 XML template of the Windows Command adapter request

<windows-command-request> <targets> <target name=""/> <target> <host></host> <user-name></user-name> <password></password> </target> </targets> <commands> <command></command> <command></command> <command></command> </commands> </windows-command-request>

Figure 234 shows an XML sample of the adapter request for the Windows Command adapter. In this sample, the first target references the adapter configuration and the second target is a dynamic target. Figure 234 XML sample of the Windows Command adapter request
<windows-command-request> <targets> <target name="host1"/> <target> <host>server3</host> <user-name>user</user-name> <password>test</password> </target> </targets> <commands> <command>chdir</command> </commands> </windows-command-request>

NOTE
The command must be entered as if it were being keyed at the system prompt. The adapter appends cmd /c to the beginning of the command as needed.

Figure 235 shows an XML sample of the adapter request for the Windows Command adapter with the systeminfo command. You must include the domain information in the systeminfo command only if you want to execute the command on a remote host.

Chapter 3

Using Terminal adapters

319

Windows Command adapter request

Figure 235 XML sample of the Windows Command with systeminfo command
<windows-command-request> <targets> <target> <host>server3</host> <user-name>user</user-name> <password>test</password> </target> </targets> <commands> <command>systeminfo /s remotehost /u domain\user /p pwd /fo CSV</command> </commands> </windows-command-request>

When a relative path is specified in the adapter request, the Windows Command adapter searches for the script in the working directory on the target computer. It does not transfer the script from the peer to the remote computer. Figure 236 shows an XML sample of the adapter request for the Windows Command adapter with a relative path. Figure 236 XML sample of the Windows Command adapter request with a relative path
<windows-command-request> <commands> <command working-dir= D:\scripts>.\SampleScript.ps1</command> <command working-dir= D:\scripts>.\OSProperties.ps1</command> </commands> </windows-command-request>

Figure 237 shows an XML sample of the adapter request for the Windows Command adapter with a full path. Figure 237 XML sample of the Windows Command adapter request with a full path
<windows-command-request> <commands> <command>D:\scripts\SampleScript.ps1</command> <command>D:\scripts\OSProperties.ps1</command> </commands> </windows-command-request>

320

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter response

Figure 238 shows an XML sample of the adapter request for the Windows Command adapter with script execution. Figure 238 XML sample of the Windows Command adapter request with script execution
<windows-command-request> <targets> <target> <host>server3</host> <user-name>user</user-name> <password>test</password> </target> </targets> <commands> <command>c:\TestScript.vbs arg1 arg2</command> </commands> </windows-command-request>

Windows Command adapter response

The Windows Command adapter returns an adapter response that contains the details for the command executed by the adapter request. Table 110 describes the elements of a Windows Command adapter response. Table 110
Element <requestmetadata> <status>

Elements of a Windows Command adapter response (part 1 of 2)

Description Contains the request level summary information Indicates the status of the request Valid values: success, error

<error>

Indicates the error message returned when the value of the <status> element is error When the value of the <status> element success, this element is absent.

<targetsoutput> <targetoutput> <targetmetadata> <os-id> <os-version> <status>

Contains the command output for all target computers Contains the command output for a specific target The host attribute provides the host name or the IP address of the target computer. Contains the target level summary information Indicates the system type for the target computer Indicates the system version for the target computer Indicates the status of the target connection Valid values: success, error

Chapter 3

Using Terminal adapters

321

Windows Command adapter response

Table 110
Element <error>

Elements of a Windows Command adapter response (part 2 of 2)

Description Contains the error message if a target level error occurs When the value of the <status> element is success, this element is absent.

<commandsoutput> <commandoutput> <metadata> <command> <line-count> <executionmilliseconds> <exit-code>

Contains the command responses for all the commands executed on the target computer Contains the command response for a specific command Contains the command summary information Specifies the command executed Specifies the number of lines returned by the command Specifies the duration of the command execution, in milliseconds Specifies the exit code returned by the target after the command is executed A successful execution returns a value of 0. An unsuccessful execution returns a nonzero value. If the exit code is not obtained, a value of 9999 is returned by default. If the value returned for the <exit-code> is not 0 or 9999, the value of the <status> element is error, and an <error> element is present in the response.

<status>

Indicates the status of the command execution Valid values: success, error

<error>

Contains the error message if the execution of a command is interrupted When the value of the <status> element is success, this element is absent.

<output> <line>

Contains the lines that result from the command Specifies the output resulting from the command The index attribute indicates the sequence in which the line is returned. This can also contain a response returned when the <exit-code> is non-zero.

322

BMC Atrium Orchestrator Base Adapters User Guide

Windows Command adapter response

Figure 239 illustrates an XML sample of the adapter response for the Windows Command adapter using the default xCmd protocol. Figure 239 XML sample of the Windows Command adapter response using the xCmd utility
<windows-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="server3"> <metadata> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ipconfig</command> <line-count>16</line-count> <execution-milliseconds>1657</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Copyright 2010 BMC Software Ltd, Version: 1.0</line> <line index="2">Connecting to remote service...</line> <line index="3">Connected to remote host.</line> <line index="4">Windows IP Configuration</line> <line index="5">Ethernet adapter Private Network:</line> <line index="6"> Connection-specific DNS Suffix . : </line> <line index="7"> IP Address. . . . . . . . . . . . : 92.0.0.1</line> <line index="8"> Subnet Mask . . . . . . . . . . . : 255.0.0.0</line> <line index="9"> Default Gateway . . . . . . . . . :gateway1</line> <line index="10">Ethernet adapter Public network:</line> <line index="11"> Connection-specific DNS Suffix . <line index="12"> IP Address. . . . . . . . . . . . <line index="13"> Subnet Mask . . . . . . . . . . . <line index="14"> Default Gateway . . . . . . . . . <line index="15">Remote application exited with code: </output> </command-output> </commands-output> </target-output> </targets-output> </windows-command-output> : </line> : 192.168.10.2</line> : 255.255.252.0</line> : 192.168.1.1</line> 0</line>

Chapter 3

Using Terminal adapters

323

Windows Command adapter response

Figure 240 illustrates an XML sample of the adapter response for the Windows Command adapter using the SSH protocol. Figure 240 XML Sample of the Windows Command adapter response using SSH
<windows-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host="server3"> <metadata> <os-id>Windows XP</os-id> <os-version>5.1</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>ipconfig</command> <line-count>25</line-count> <execution-milliseconds>625</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1"></line> <line index="2">Windows IP Configuration</line> <line index="3"></line> . . . <line index="20"> Subnet Mask . . . . . . . . . . . : 255.0.0.0</line> <line index="21"> Default Gateway . . . . . . . . . :gateway1 </line> <line index="22"></line> <line index="23">Ethernet adapter Network Connect Adapter:</line> <line index="24"></line> <line index="25"> Media State . . . . . . . . . . . : Media disconnected</line> </output> </command-output> </commands-output> </target-output> </targets-output> </windows-command-output>

324

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell adapter

Figure 241 illustrates an XML sample of the adapter response for the Windows Command adapter with script execution. Figure 241 XML sample of the Windows Command adapter response with script execution
<windows-command-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host=" server3"> <metadata> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command> c:\TestScript.vbs arg1 arg2</command> <line-count>6</line-count> <execution-milliseconds>1657</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index="1">Copyright 2010 BMC Software Ltd, Version: 1.0</line> <line index="2">Connecting to remote service...</line> <line index="3">Connected to remote host.</line> <line index="4">This is demo of script execution in windows commandline adapter</line> <line index="5">Remote application exited with code: 0</line> </output> </command-output> </commands-output> </target-output> </targets-output> </windows-command-output>

PowerShell adapter
The BMC Atrium Orchestrator base adapter for Microsoft Windows PowerShell product is used to execute PowerShell commands on remote host computers running Microsoft Windows PowerShell. The Microsoft Windows PowerShell base adapter consists of an actor adapter only. The BMC Atrium Orchestrator base adapter for Microsoft Windows PowerShell does not utilize the xCmd utility, if the target computer is the local host computer. The adapter does not use the xCmd utility in the following cases:
s

When you specify an empty configuration and you do not specify a dynamic target in the adapter request When you do not specify a host in the <target> block of the adapter configuration or the <host> tag in the dynamic target request

If you specify 127.0.0.1 or the host name of the local computer, the adapter still uses the xCmd utility for executing PowerShell commands.

Chapter 3

Using Terminal adapters

325

PowerShell adapter

NOTE
A monitor adapter is not available for Microsoft Windows PowerShell.

The actor adapter for Microsoft Windows PowerShell provides operations that use the PowerShell command-line interface to execute commands. The actor adapter for Microsoft Windows PowerShell supports the following command attributes:
s s s

s s

Multiple Configuration nodes Dynamic Targets FAT CommandsCommand attributes: timeout-secs continue-on-failure ignore-response working- dir os-id os-version Command encryption Password encryption

The actor adapter for Microsoft Windows PowerShell does not support the following

command attributes:
s s s s

command-dir is-special-character

Proxy commands Verification of OS

NOTE
s

Before executing a script file or a console file for working-dir, prepend ./ before the script file name. Example: samplescript.ps1 must be executed as ./samplescript.ps1.

The value for working-dir must not end with a backslash, however two backslashes are permitted. Example: work-dir=c:\tempdir or work-dir=c:\tempdir\\

326

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell adapter post-installation tasks

Figure 242 shows an XML template for the PowerShell adapter configuration. Figure 242 XML template of the PowerShell adapter configuration
<config> <target></target> <user-name></user-name> <password></password> <powershell-version></powershell-version> <powershell-consolefile></powershell-consolefile> <use-userprofile></use-userprofile> <script-file-path></script-file-path> </config>

This section describes the configuration, request format, and response format of the PowerShell adapter:

PowerShell adapter postinstallation tasks PowerShell adapter request PowerShell adapter request

PowerShell adapter configuration PowerShell adapter response

PowerShell adapter post-installation tasks

You can enable the PowerShell adapter on BMC Atrium Orchestrator peers running on a Microsoft Windows XP, Microsoft Windows Server 2003, or Microsoft Windows Server 2008 operating system. Also, the permission levels for the BMC Atrium Orchestrator service on the Windows peer must be configured to allow the adapter to communicate properly.

To set permissions for the PowerShell adapter 1 Log on to the Windows peer on which the PowerShell application adapter is to be
enabled.

2 Navigate to Start => Control Panel => Administrative Tools => Services. 3 Right-click the BMC Atrium Orchestrator AP, BMC Atrium Orchestrator LAP, BMC
Atrium Orchestrator CDP, or BMC Atrium Orchestrator HACDP service, and select Properties from the pop-up menu.

4 Click the Log On tab. 5 Select This account. 6 Type the user name for this service.
Chapter 3 Using Terminal adapters 327

PowerShell adapter configuration

NOTE
The specified user must have the ability to communicate externally and utilize a communication interface.

7 Type the corresponding password in the Password and Confirm Password text
boxes.

8 Click Apply. 9 Click OK. 10 Restart the BMC Atrium Orchestrator AP, BMC Atrium Orchestrator LAP, BMC Atrium
Orchestrator CDP, or BMC Atrium Orchestrator HACDP service.

PowerShell adapter configuration

Adapter type: bmc-adapter-microsoft-windows-powershell-actor [version]. Default name: MicrosoftPowerShell To configure the PowerShell adapter, see Configuring the adapter on page 14. BMC recommends that you do not use empty elements in an adapter configuration because they might cause errors. Table 111 describes the adapter configuration elements for the PowerShell adapter that you can specify by 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. Table 111
UI label Target

PowerShell adapter configuration node elements (part 1 of 2)

Element <target> Definition Required Specifies the fully-qualified (absolute) host name or IP No address of the remote or the local computer Default value: localhost

User Name

<user-name>

Specifies the user name required for remote host computer authentication This user must have administrative roles and privileges on the remote host computer. This element depends on the users environment.

Conditional

328

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell adapter configuration

Table 111
UI label Password

PowerShell adapter configuration node elements (part 2 of 2)

Element <password> Definition Specifies the password that corresponds to the username provided This element depends on the users environment. Required Conditional

Powershell Version

<powershell- Specifies the version of Microsoft Windows version PowerShell If the <powershell-consolefile> element is specified, do not use this element.

Conditional

Powershell Consolefile

<powershell- Specifies the Microsoft Windows PowerShell console consolefile> file to be loaded If the <powershell-version> element is specified, do not use this element. Valid value: .psc1

Conditional

Use Userprofile <useDetermines whether to load the user profile userprofile> Valid values: true, false Script File Path <scriptfile-path>

No

Specifies the script file path relative to the local (peer) No or target (remote) computer PowerShell must be installed on the target computer. Valid values: local (default), remote

Figure 243 shows an XML sample for the PowerShell adapter configuration. Figure 243 XML sample of the PowerShell adapter configuration
<config> <target>host1</target> <user-name>user1</user-name> <password>pass1</password> <powershell-version>1.0</powershell-version> <use-userprofile>true</use-userprofile> <script-file-path>local</script-file-path> </config>

Chapter 3

Using Terminal adapters

329

PowerShell adapter request

NOTE
s

The PowerShell actor adapter supports empty and multiple configurations. The <powershell-consolefile> element specifies the console file, which is the library used by PowerShell. Do not use the <powershell-version> and <powershell-consolefile> elements in the same request. The PowerShell adapter considers the target as localhost and executes the command on command line when: The adapter has an empty configuration, and the dynamic target is not defined You do not define a dynamic target, and the configuration has a blank target or no target You define a dynamic target and do not specify the host name

Figure 244 shows an XML sample for a PowerShell adapter configuration with the <powershell-consolefile> tag. Figure 244 XML sample of the PowerShell adapter configuration with <powershell-consolefile> tag
<config> <target>host1</target> <user-name>user1</user-name> <password>pass1</password> <powershellconsolefile>Microsoft.EnterpriseManagement.OperationsManager.ClientShell.Console.psc1 </powershell-consolefile> </config>

PowerShell adapter request

The PowerShell actor adapter sends commands to PowerShell and receives responses and results from the CLI of PowerShell. The PowerShell actor adapter works with PowerShell 1.0. To configure an adapter request to communicate with the host computer that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

330

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell adapter request

To override the configuration properties in the adapter configuration, include the target, user-name, and password elements in the request. Table 112 describes the adapter request elements for the PowerShell adapter. Table 112
Element <targets> <target>

Adapter request elements for the PowerShell adapter

Definition Contains the <target> elements Used to reference a target in the request If the target element is not defined, the default target in the adapter configuration is used. Required No No

<host>

Contains the host name or the IP address of the remote or local computer This element is required for defining a dynamic target computer.

No

<user-name> Contains the user name to be used for authentication on the remote host Conditional computer This element is required to define a dynamic target computer. This user must have administrative roles and privileges on the remote host computer. This element depends on the users environment. <password> Contains the password corresponding to the specified user-name for authentication on the remote host computer This element is required to define a dynamic target computer. This element depends on the users environment. <powershell Specifies the version of Microsoft Windows PowerShell on which the -version> command is to be executed Valid value: 1.0 <powershell Specifies the PowerShell console file to be loaded consolefile > <useDetermines whether the user profile is to be loaded userprofile > Valid values: true, false <commands> <command> Contains a single or multiple command elements Contains the PowerShell command to be executed No No Conditional

No

Yes Yes

Chapter 3

Using Terminal adapters

331

PowerShell adapter request

Figure 29 shows an XML template for the PowerShell actor adapter request. Figure 245 XML template of the PowerShell adapter request
<powershell-request> <targets> <target> <host></host> <user-name></user-name> <password>testpass</password> <powershell-version>1.0</powershell-version> <powershell-consolefile>pshell.psc1</powershell-consolefile> <use-userprofile>true</use-userprofile> </target> </targets> <commands> <command></command> <command></command> </commands> </powershell-request>

Figure 246 shows the adapter request for the PowerShell adapter, where multiple PowerShell commands are used in a single adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 246 XML sample of the PowerShell adapter request
<powershell-request> <commands> <command>get-alert -criteria {Name LIKE 'Performance%' }</command> <command>get-service</command> </commands> </powershell-request>

Figure 247 shows an example of the Powershell adapter request with the get-service PowerShell command. Figure 247 XML sample of the PowerShell adapter request with get-service command
<powershell-request> <targets> <target> <host>computer2</host> <user-name>testuser</user-name> <password>testpass</password> <powershell-version>1.0</powershell-version> <powershell-consolefile>pshell.psc1</powershell-consolefile> <use-userprofile>true</use-userprofile> </target> </targets> <commands> <command>get-service</command> </commands> </powershell-request>

Figure 248 shows an XML sample for the PowerShell adapter request with relative path. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

332

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell adapter response

Figure 248 XML sample of the PowerShell adapter request with relative path
<powershell-request> <commands> <command working-dir= D:\scripts>./SampleScript.ps1</command> <command working-dir= D:\scripts>./OSProperties.ps1</command> </commands> </powershell-request>

Figure 249 shows an XML sample for the PowerShell adapter request with full path. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 249 XML sample of the PowerShell adapter request with full path
<powershell-request> <commands> <command>D:\scripts\SampleScript.ps1</command> <command>D:\scripts\OSProperties.ps1</command> </commands> </powershell-request>

PowerShell adapter response

The PowerShell adapter response contains the result returned from an adapter request. Figure 250 shows an XML sample for the PowerShell adapter response with get-service PowerShell command.

Chapter 3

Using Terminal adapters

333

PowerShell adapter response

Figure 250 XML sample of the PowerShell adapter response

<powershell-output> <metadata> <status>success</status> </metadata> <targets-output> <target-output host = "10.128.248.76"> <metadata> <os-id>Windows 2003</os-id> <os-version>5.2 Build 3790 Service Pack 2</os-version> <status>success</status> </metadata> <commands-output> <command-output> <metadata> <command>Get-Service</command> <line-count>170</line-count> <execution-milliseconds>7735</execution-milliseconds> <exit-code>0</exit-code> <status>success</status> </metadata> <output> <line index = "1">Copyright 2010 BMC Software Ltd, Version: 1.1</line> <line index = "2">Connecting to remote service...</line> <line index = "3">Connected to remote host.</line> <line index = "4">Status Name DisplayName</line> <line index = "5">------------------</line> *** command response *** <line index = "169">Stopped xmlprov Network Provisioning Service</line> <line index = "170">Remote application exited with code: 0</line> </output> </command-output> </commands-output> </target-output> </targets-output> </powershell-output>

334

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

4
336 337 339 341 345 349 351 354 354 356 356 358 358 362 373 380 381 382 385 386 386 387 387 388 389 393 394 395 396 397 398 398 405 405
335

Additional base adapters

This chapter presents the following topics: HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter request with a get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter response to a request with get action . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter request with a post action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter response with post action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter request with put action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter response with put action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter request with a delete action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP adapter response with a delete action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying header fields in the HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites for the JMS adapter with IBM WebSphere MQ. . . . . . . . . . . . . . . . JMS actor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter request with get action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter response with get action . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter request with notification action . . . . . . . . . . . . . . . . . . . . . . SNMP actor adapter response with notification action . . . . . . . . . . . . . . . . . . . . . SNMP monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL actor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMW Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL actor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL actor adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL actor adapter requestStandard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 4 Additional base adapters

HTTP adapter

SQL actor adapter responseStandard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 SQL actor adapter requestParameterized Statement . . . . . . . . . . . . . . . . . . . . . 411 SQL actor adapter responseParameterized Statement . . . . . . . . . . . . . . . . . . . . 416 Oracle XMLType data type support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Installing JDBC OCI Instant Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 SQL monitor adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 SQL monitor adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 SQL monitor adapter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 SQL adapter FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Web Services adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Web Services adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Web Services adapter request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Web Services adapter requestmethod one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Web Services adapter responsemethod one. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Web Services adapter requestmethod two. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Web Services adapter responsemethod two . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Web Services adapter requestJAX-WS Approach . . . . . . . . . . . . . . . . . . . . . . . . 455 Web Services adapter request for Make SOAP RequestPayload mode . . . . . . 455 Web Services adapter response for Make SOAP RequestPayload mode . . . . 456 Web Services adapter request for Make SOAP RequestMessage mode . . . . . 458 Web Services adapter response for Make SOAP RequestMessage mode . . . . 465 Web Services adapter request for Poll Asynchronous Response . . . . . . . . . . . . . 467 Web Services adapter response for a request with Poll Asynchronous Response. . 468 Differences in the methods used to define a Web Services adapter request. . . . 469

HTTP adapter
The HTTP adapter sends an HTTP or HTTPS request to a URL and processes the response to return the web page in XML format. This adapter does not support multiple configuration nodes. However, you can configure multiple HTTP adapters within Grid Manager, each with a required configuration node and an unique adapter name. The HTTP adapter might use a standard HTTP proxy server for establishing outbound HTTP connections. The HTTP adapter supports only basic authentication for the proxy server that is used. This section describes the configuration, request format, and response format of the HTTP adapter:

HTTP adapter configuration HTTP adapter request with a post action

HTTP adapter request with a delete action HTTP adapter response to a request with get action

336

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter configuration

HTTP adapter response with put action HTTP adapter request with a get action HTTP adapter response with post action

HTTP adapter request with put action HTTP adapter response with a delete action

HTTP adapter configuration

Adapter type: ro-adapter-http[version] Default adapter name: HTTPAdapter The Properties field in the adapter configuration of Grid Manager is a required field. If the default values are acceptable for all elements, you can enter a configuration node, <config/>, in the Properties field. When you set a configuration node, the adapter uses the default values for all the elements. If you use a proxy server for Internet connectivity, use the proxy settings shown in the <config> section in Figure 252. If your environment does not require a proxy server, set a configuration node. BMC recommends that you do not include unused elements in the adapter configuration because they might cause the adapter to enter a fault state. To configure the HTTP adapter, see Configuring the adapter on page 14. Table 113 describes the adapter configuration elements for the HTTP adapter that you can specify by 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. Table 113
UI label Data Format

Configuration elements for the HTTP adapter (part 1 of 2)

Element <dataformat> Description Specifies the format for the output The configuration values can be overridden in the adapter request. Valid values: HTML (default), XML, XHTML Note: If an invalid value is specified for this element, the default value HTML is used. Required No

Request Timeout

<requesttimeout>

Specifies the time (in seconds) to wait when establishing a connection Default value: 10 seconds.

No

Chapter 4 Additional base adapters

337

HTTP adapter configuration

Table 113
UI label None

Configuration elements for the HTTP adapter (part 2 of 2)

Element <proxysettings> Description Contains the elements that define the HTTP proxy settings If you provide this element, you must also specify the <host> and <port> elements You must specify the <user-name> and <password> elements only if the authentication scheme is enabled on the proxy server. Required No

None

<host>

Specifies the host name or the IP address of the destination host for the HTTP request This element is required if you use <proxysettings>.

Conditional

None

<port>

Specifies the destination port for the HTTP request This element is required if you use <proxysettings>.

Conditional

None

<user-name>

Specifies the name of the user You must specify the <user-name> and <password> elements only if the authentication scheme is enabled on the proxy server.

Conditional

None

<password>

Specifies the password for the user on the specified host You must specify the <user-name> and <password> elements only if the authentication scheme is enabled on the proxy server.

Conditional

Figure 251 shows an XML template for the HTTP adapter configuration. Figure 251 XML template of the HTTP adapter configuration
<config> <data-format></data-format> <request-timeout></request-timeout> <proxy-settings> <host></host> <port></port> <user-name></user-name> <password></password> </proxy-settings> </config>

Figure 252 on page 339 shows an XML sample for the HTTP adapter configuration. As shown in Figure 252, to resolve proxy settings errors, enter the proxy settings for the
Internet connection. To resolve authentication errors, enter a valid username and password.

338

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with a get action

Figure 252 XML sample of the HTTP adapter configuration

<config> <data-format>HTML</data-format> <request-timeout>15</request-timeout> <proxy-settings> <host>10.10.75.120</host> <port>3128</port> <user-name>jones</user-name> <password>bmc1234</password> </proxy-settings> </config>

HTTP adapter request with a get action

The HTTP adapter can retrieve data from a specified URL by using a get action. You must enter the get action in the Action field of the Properties tab for the Call Adapter activity. When you use the Transform Editor in BMC Atrium Orchestrator Development Studio to create the adapter request, you must enclose the request template within <request-data> tags. Table 114 describes the adapter request elements for the HTTP adapter with a get action. Table 114
Element <url> <use-sslcertificate> <allowunsignedcertificate> <installcertificate> <passphrase>

Elements for an HTTP adapter request with a get action (part 1 of 2)

Description Specifies the URL for the target page Determines whether to establish a secure connection Valid values: true, false (default) Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false (default) Determines whether to install certificates Valid values: true, false (default) Specifies the Java Standard Trust Keystore passphrase Default value: changeit No No No Required Yes No

<data-format>

Indicates the data type for the adapter response Valid values: XML (default), HTML

No

<httpconnectionproperties>

Verifies basic authentication This element has nested <username> and <password> elements.

No

Chapter 4 Additional base adapters

339

HTTP adapter request with a get action

Table 114
Element

Elements for an HTTP adapter request with a get action (part 2 of 2)

Description Specifies whether Windows NT LAN Manager ((NTLM version 1)) authentication is needed for the given user credentials Valid values: true, false (default) If the value of the parameter is true, NTLM (version 1) authentication is used to authenticate the user; otherwise, basic authentication is used. Required No

<ntlmauthentication>

<Content-Type>

Specifies the type of data format for HTTP content

No

Figure 253 shows an XML template for the HTTP adapter request with a get action. Figure 253 XML template of the HTTP adapter request with a get action
<httpadapterRequest> <action></action> <data-format></data-format> <http-connection-properties> <user-name>test</user-name> <password>this</password> </http-connection-properties> </httpadapterRequest>

Figure 254 shows an XML sample of the HTTP adapter request with a get action. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 254 XML sample of the HTTP adapter request with a get action
<httpadapterRequest> <action>http://www.yahoo.com/</action> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>true</allow-unsigned-certificate> <passphrase>true</passphrase> <data-format>XHTML</data-format> <http-connection-properties> <user-name>user</user-name> <password>pass123</password> </http-connection-properties> </httpadapterRequest>

Figure 255 shows an XML sample for the HTTP adapter request with NTLM authentication. NTLM authentication is an application protocol used in various Microsoft network protocol implementations and is used throughout Microsoft systems as an integrated single sign-on mechanism.

340

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter response to a request with get action

Figure 255 XML sample of the HTTP adapter request with NTLM authentication
<http-adapter-request> <action>http://someHost/_vti_bin/UserGroup.asmx</action> <use-ssl-certificate></use-ssl-certificate> <install-certificate></install-certificate> <allow-unsigned-certificate></allow-unsigned-certificate> <passphrase></passphrase> <data-format>XHTML</data-format> <http-connection-properties> <user-name>USERDOMAIN\user123</user-name> <password>password</password> <ntlm-authentication>true</ntlm-authentication> <Content-Type>text/html</Content-Type> </http-connection-properties> </http-adapter-request>

HTTP adapter response to a request with get action

The HTTP adapter generates a response to the HTTP request (URL) defined in the adapter request. The response depends on the <Content-Type> element of the HTTP server response and the <data-format> element in the adapter request. Table 115 describes the elements of the response to an HTTP adapter request with a get action, when <data-format> is HTML for any <Content-Type> of HTTP server response. Table 115
Element <status>

Elements of an HTTP adapter response to a request with get action when <data-format> is HTML for any <Content-Type> of HTTP response (part 1 of 2)
Description Specifies the status of the adapter request Valid values: success, error

<metadata> <status-line> <code>

Contains the <status> element Contains the <code> and <reason> elements Specifies the numeric status code for the response The <code> response element returns 10000 for a connection and read timeout or when the web service is down.

<reason> <header-lines>

Specifies the reason associated with the status code Contains the <field-name> element

Chapter 4 Additional base adapters

341

HTTP adapter response to a request with get action

Table 115
Element

Elements of an HTTP adapter response to a request with get action when <data-format> is HTML for any <Content-Type> of HTTP response (part 2 of 2)
Description Specifies the field name returned from the adapter request in the HTTP header data This element is variable and depends on the field returned. This element is a child of the <header-lines> tag and is shown in the response as follows: <header-lines> <!-- header of the http response --> [<field-name>][</field-name>] </header-lines> The response can return multiple fields, as shown in the following example: <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>391</Content-Length> <Date>Mon, 05 Apr 2010 09:32:22 GMT</Date>

<field-name>

<message-body>

Contains the message body of the HTTP response in text format

NOTE
The HTTP adapter request is the request generated by the HTTP adapter; the HTTP request is the request sent to the HTTP server.

Figure 256 shows an XML sample for HTTP adapter response with get action, when <data-format> is HTML for any Content-Type of HTTP server response. Figure 256 XML sample of the HTTP adapter response to a request with get action when <dataformat> is HTML for any <Content-Type>
<httpadapterResponse> <metadata> <status>success</status> </metadata> <status-line> <!-- status of http response --> <code>10000</code> <reason></reason> </status-line> <header-lines> <!-- header of the http response --> <[field-name]></[field-name]> ... </header-lines> <message-body> <!-- message body of the http response in HTML/XHTML/XML...> </message-body> </httpadapterResponse>

342

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter response to a request with get action

Table 116 describes the elements of a HTTP adapter response that is shown in Figure 257. Table 116
Element <status-line> <code> <reason> <field-name>

Elements of an HTTP adapter response to a request with a get action when <dataformat> is XHTML or XML and <Content-Type> is well-formed text, HTML, or XML
Description Contains the <code> and <reason> elements Specifies the numeric status code of a response Specifies the reason associated with the status code Specifies the field name returned from the adapter request The element name is variable and depends on the field returned.

<header-lines> Contains the <field-name> element

<message-body> Contains the message body of the HTTP response in XML format or uncorrected HTML format, not in character data (CDATA) format Note: If the output is not in the specified format, the output is enclosed in <non-xmldata-response>.

Figure 257 shows an XML sample for the HTTP adapter response to an HTTP adapter request with a get action when:
s

<data-format> is XHTML or XML, <Content-Type> of the HTTP server

response is TEXT or HTML, and the HTTP server response is a well-formed XHTML or XML after syntax correction (cleaning of malformed or faulty HTML using the JTidy tool) <data-format> is XHTML or XML, <Content-Type> of the HTTP server response is TEXT or HTML/XML, and the HTTP server response is well-formed XHTML or XML

NOTE
<script> and <style> elements are deleted from the HTTP server response for XHTML data format.

Chapter 4 Additional base adapters

343

HTTP adapter response to a request with get action

Figure 257 XML sample of the HTTP adapter response to an HTTP adapter request with a get action when <data-format> is XHTML or XML and <Content-Type> of HTTP response is wellformed text, HTML, or XML
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <[field-name]></[field-name]> </header-lines> <message-body> <!-- message body of the http response in well formed XML/HTML --> </message-body> </httpAdapterResponse>

Figure 258 describes the elements of an HTTP adapter response to a request with get action, when:
s

<data-format> is XHTML or XML, <Content-Type> of the HTTP server

response is TEXT or HTML, and the HTTP server response is not well-formed XHTML or XML after syntax correction (cleaning of malformed or faulty HTML using the JTidy tool) <data-format> is XHTML or XML, <Content-Type> of the HTTP server response is TEXT or HTML/XML, and the HTTP server response is not wellformed XHTML or XML

NOTE
If the output is not in the format that you want, it is enclosed in <non-xmldataresponse> tags.

Figure 258 HTTP adapter response elements to a request with a get action when <data-format> is XHTML or XML and <Content-Type> of the HTTP response is not well-formed TEXT, HTML, or XML
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <[field-name]></[field-name]> ... </header-lines> <message-body> <non-xml-data-response> <!-- message body of the http response in not well formed XML/HTML --> </non-xml-data-response> </message-body> </httpAdapterResponse>

344

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with a post action

HTTP adapter request with a post action

The post operation sends data to a specified URL. The adapter request with a post action uses the following formats:
s

single element parent and child entry, key-value

When you use the transform editor in BMC Atrium Orchestrator Development Studio to create the adapter request, you must enclose the request template within <request-data> tags. Table 117 describes the adapter request elements for the HTTP adapter with post action. Table 117
Element <url>

Adapter request elements for HTTP adapter with post action

Description Specifies the URL defining the location of the content to be sent Required Yes No

<use-sslSpecifies whether to establish a secure connection certificate> Valid values: true, false (default) <allowSpecifies whether to allow unsigned certificates from trusted zones unsignedcertificate> Valid values: true, false (default) <installSpecifies whether to install certificates certificate> Valid values: true, false (default) <passphrase> Specifies the Java Standard Trust Key Store passphrase Default value: changeit <user name> <password> <dataformat> Specifies the user name to be used for basic authentication Specifies the password corresponding to the user name provided for basic authentication Indicates the data type for the adapter response Valid values: XML (default), HTML

No

No

No

No No No

Chapter 4 Additional base adapters

345

HTTP adapter request with a post action

Table 117
Element

Adapter request elements for HTTP adapter with post action

Description Required

<ntlmSpecifies if Windows NT LAN Manager (NTLM version 1) authentication is No authenticati needed for the given user credentials on> Valid values: true, false (default) If the value of the parameter is true, NTLM version 1 authentication is used to authenticate the user; else, basic authentication is used. <data> Contains the data to be posted Data can be used 3 ways: Simple text form, Parent and child format, and key and entry format. No

Figure 259 shows an XML sample of the HTTP adapter request with a post action and in the single element format, which uses a single <data> element to contain the data to be posted. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 259 HTTP adapter request with a post actionsingle element format
<http-adapter-request> <http-connection-properties/> <action>http://10.128.249.21:8080/httpclientoperations/HttpClientServlet</action> <use-ssl-certificate>false</use-ssl-certificate> <install-certificate>false</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <passphrase>changeit</passphrase> <data>This is the sample String.</data> </http-adapter-request>

Figure 260 shows an XML sample of an HTTP adapter request with a post-action and in the parent and child format, which uses a parent or a child method for containing data, with a single <parent> element inside the <data> element and an unlimited number of <child> elements of that parent. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 260 HTTP adapter request with a post actionparent and child format
<http-adapter-request> <http-connection-properties/> <action>http://10.128.249.21:8080/httpclientoperations/HttpClientServlet</action> <use-ssl-certificate>false</use-ssl-certificate> <install-certificate>false</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <passphrase>changeit</passphrase> <data> <parent> <child1>Child 1 Data</child1> <child2>Child 2 Data</child2> </parent> </data> </http-adapter-request>

346

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with a post action

Figure 261 shows an XML sample of an HTTP adapter request with a post action and in the entry, key, and value format, which uses an <entry> element that contains a key-value pair, specified in a <key> and a <value> element. Figure 261 HTTP adapter request with post actionentry, key-value format
<httpadapterRequest> <action>https://${Https_RemoteMachine}:${httpsPort}/HttpTestApp//EchoServlet</action> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>true</allow-unsigned-certificate> <data-format>xhtml</data-format> <data> <entry> <key>Name</key> <value> <foo> <bar>1</bar> <bar>2</bar> </foo> </value> </entry> <entry> <key>Credit Card</key> <value>1234</value> </entry> <entry> <key>Debit Card</key> <value>12345</value> </entry> </data> <http-connection-properties> <user-name>admin</user-name> <password>admin123</password> </http-connection-properties> </httpadapterRequest>

Table 118 describes the elements of an HTTP adapter request with a post action in any format. Table 118
Element <action> <use-sslcertificate> <allowunsignedcertificate> <installcertificate> <passphrase>

Elements of an HTTP request with a post actionentry, key-value pair tags format (part 1 of 2)
Description Specifies the URL for the target page Specifies whether to establish a secure connection Valid values: true, false (default) Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false (default) Specifies whether to install certificates Valid values: true, false (default) Specifies the Java Standard Trust Key Store passphrase Default value: changeit No No No Required Yes No

Chapter 4 Additional base adapters

347

HTTP adapter request with a post action

Table 118
Element

Elements of an HTTP request with a post actionentry, key-value pair tags format (part 2 of 2)
Description Indicates the data type for the adapter response Valid values: XML, HTML (default) Required No

<data-format>

<data>

Contains the information to be posted This information can be contained within the <data> element directly, or it can use <parent> and <child> or <key> and <value> tags to contain the data.

Yes

<httpconnectionproperties> <ntlmauthentication>

Verifies basic authentication It has nested <username> and <password> tags. Specifies if Windows NT LAN Manager (NTLM version 1) authentication is needed for the given user credentials Valid values: true, false (default) If the value of this parameter is true, NTLM version 1 authentication is used to authenticate the user; otherwise, basic authentication is used.

No

No

Figure 262 on page 348 shows an XML sample of the HTTP adapter request with post-action, entry, key-value pair tags format that uses a key or value method. With this option, the <data> element contains one or more <entry> elements. Within each <entry> element a <key> and <value> element is defined. The <value> element can be a simple value or an XML document. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 262 XML sample of the HTTP adapter request with post actionentry, key, and value pair tags format
<http-adapter-request> <http-connection-properties/> <action>http://10.128.249.21:8080/httpclientoperations/HttpClientServlet</action> <use-ssl-certificate>false</use-ssl-certificate> <install-certificate>false</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <passphrase>changeit</passphrase> <data> <entry> <key>Key 1</key> <value>Value 1</value> </entry> </data> </http-adapter-request>

348

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter response with post action

HTTP adapter response with post action

The HTTP adapter generates a response to the HTTP request (URL) defined in the adapter request. The response format depends on <Content-Type> of the HTTP server response. Figure 263 shows an XML sample for the HTTP adapter response with post-action, simple text data format. Figure 263 XML sample of the HTTP adapter response with post actionsimple text data format
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>391</Content-Length> <Date>Mon, 05 Apr 2010 09:32:22 GMT</Date> </header-lines> <message-body><Html><Title>Testing Application for HTTP Adapter</Title><Head></Head><Title>Testing Application for HTTP Adapter</Title><Head></Head><Body>Hi, I am inside the doPost() Method of the EchoServlet, <br><br><br><br> <br><br> Query String : null<br><br><BR><BR> XML Text : This is the sample String.<Center> Copyrights &copy;, Developed By Test User </Center></Body></Html></message-body> </httpAdapterResponse>

Figure 264 on page 350 shows the XML sample for HTTP adapter response with post actionparent and child format.

NOTE
<script> and <style> elements are deleted from the HTTP response for XHTML data format.

Chapter 4 Additional base adapters

349

HTTP adapter response with post action

Figure 264 XML sample of the HTTP adapter response with post actionparent and child format
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>444</Content-Length> <Date>Mon, 05 Apr 2010 09:33:50 GMT</Date> </header-lines> <message-body> <Html>

<Title>Testing Application for HTTP Adapter</Title> <Head></Head> <Title>Testing Application for HTTP Adapter</Title> <Head></Head> <Body>Hi, I am inside the doPost() Method of the EchoServlet, <br><br> <br><br> <br><br> Query String : null<br><br><BR><BR> XML Text : <parent> <child1>Child 1 Data</child1> <child2>Child 2 Data</child2></parent><Center> Copyrights &copy;, Developed By Test User </Center> </Body> </Html> </message-body>
</httpAdapterResponse>

Table 119 describes the elements of an HTTP adapter response to a request with post actionentry, key- value pair tags format. Table 119
Element <metadata> <status>

Elements of an HTTP adapter response to a request with post actionentry, key-value pair tags format
Description Contains the <status> element Specifies the status of the adapter request Valid values: success, error

<status-line> <code>

Contains the elements in the <status-line> element Specifies the numeric status code for the response Code 10000 is returned for a connection and read timeout, or if the web service is down.

<reason <header-lines>

Specifies the reason associated with the code Contains the elements in the <header-lines> element

350

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with put action

Table 119
Element

Elements of an HTTP adapter response to a request with post actionentry, key-value pair tags format
Description Specifies the specific field name and value returned from the adapter request The element name is variable, dependent on the field returned.

<field-name>

<message-body>

Contains the message body of the HTTP response in CDATA format

Figure 265 shows an XML sample for HTTP adapter response with post actionentry, key, and value pair tags format. Figure 265 XML sample of the HTTP adapter response with post actionentry, key, and value pair tags format
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>385</Content-Length> <Date>Mon, 05 Apr 2010 11:35:06 GMT</Date> </header-lines> <message-body><Html><Title>Testing Application for HTTP Adapter</Title><Head></Head><Title>Testing Application for HTTP Adapter</Title><Head></Head><Body>Hi, I am inside the doPost() Method of the EchoServlet, <br><br><br><br> <br><br> Query String : null<br><br>Key 1 Value 1<BR><BR> XML Text : <Center> Copyrights &copy;, Developed By Test User </Center></Body></Html></message-body> </httpAdapterResponse>

HTTP adapter request with put action

The put action is similar to the post action except that the put action can also send a data file to the URL. The put action requires the enclosed document to be stored under the specified URL. Data is sent in the following formats using the put action:
s s s

Simple text data XML data using <parent> and <child> tags XML data using <entity>, <key>, and <value> pairs

Chapter 4 Additional base adapters

351

HTTP adapter request with put action

Table 120 describes the adapter request elements for the HTTP adapter with put action. Table 120 Adapter request elements for the HTTP adapter with put action
Element <adapter name> Description Specifies the name of the adapter Default value: HTTPAdapter <url> <use ssl certificate> <install certificate> <allow unsigned certificate> <pass phrase> Specifies the URL defining the location where the content is to be sent Yes Specifies whether to establish a secure connection Valid values: true, false (default) Specifies whether to install certificates Valid Values: true, false (default) Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false (default) Specifies the Java Standard Trust Key Store passphrase Default value: changeit <file-path> <data format> Specifies the path of the file to be sent to the URL Indicates the desired data type for the adapter response Valid values: xml, html (default) <user name> <password> <connection properties> Specifies the user name to be used for basic authentication Specifies the password corresponding to the user name provided for basic authentication No No No No No No No Required No

Specifies an XML document that includes HTTP connection properties No which, specify a user name and password for basic authentication and set the information in the HTTP request header before executing the HTTP request Note: <user name> and <password> properties are not set in the request header and are case sensitive. For an example of connection properties, see Figure 267.

<data>

Specifies the information to be sent The information can be simple text (see Figure 268), an XML document to specify parent and child (see Figure 269) tags, or entry, key, and value pair tags (see Figure 270).

Figure 266 shows an XML sample of the HTTP adapter request with put action. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

352

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with put action

Figure 266 XML sample of the HTTP adapter request with put action
<http-adapter-request> <http-connection-properties/> <action>http://10.128.249.21:8080/httpclientoperations/HttpClientServlet </action> <use-ssl-certificate>false</use-ssl-certificate> <install-certificate>false</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <passphrase>changeit</passphrase> <file-path>/home/user1/abc.txt</file-path> <data/> </http-adapter-request>

Figure 267 XML sample of <connection-properties> element

<http-connection-properties> <Content-Type>text/html</Content-Type> <Accept>Yes</Accept> <Blob></Blob> </http-connection-properties>

Figure 268 XML sample of simple text format

Sample data that will be posted.

Figure 269 XML sample of parent and child format

<parent> <child>child value</child> </parent>

Figure 270 XML sample of entry, key, value pairs format

<entry> <key>key</key> <value>value</value> </entry>

Chapter 4 Additional base adapters

353

HTTP adapter response with put action

HTTP adapter response with put action

Figure 271 shows an XML sample of the HTTP adapter response with put action. Figure 271 XML sample of the HTTP adapter response with put action
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>386</Content-Length> <Date>Mon, 05 Apr 2010 09:29:41 GMT</Date> </header-lines> <message-body><Html><Title>Testing Application for HTTP Adapter</Title><Head></Head><Title>TestingApplication for HTTP Adapter</Title><Head></Head><Body>Hi, I am inside the doPut() Method of the EchoServlet,<br><br><br><br> <br><br> Query String : null<br><br><BR><BR> XML Text : This is the Test File.<Center>Copyrights , Developed By Test User </Center></Body></Html></message-body> </httpAdapterResponse>

HTTP adapter request with a delete action

The delete action requests the server to delete the resource identified by the request URL. Table 121 describes the adapter request elements for the HTTP adapter with a delete action. Table 121 Adapter request elements for the HTTP adapter with a delete action (part 1 of 2)
Element Description Required No <adapter name> Specifies the name of the adapter Default value: HTTPAdapter <url> <use ssl certificate> <install certificate> <allow unsigned certificate> Specifies the URL defining the location where the content is to be sent Specifies whether to establish a secure connection Valid values: true, false (default) Specifies whether to install certificates Valid Values: true, false (default) Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false (default) No No Yes No

354

BMC Atrium Orchestrator Base Adapters User Guide

HTTP adapter request with a delete action

Table 121 Adapter request elements for the HTTP adapter with a delete action (part 2 of 2)
Element <pass phrase> Description Specifies the Java Standard Trust Key Store passphrase Default value: changeit <data format> Indicates the desired data type for the adapter response Valid values: xml, html (default) <user name> <password> <connection properties> Specifies the user name to be used for basic authentication Specifies the password corresponding to the user name provided for basic authentication Specifies an XML document that includes HTTP connection properties which, specify a user name and password for basic authentication and set the information in the HTTP request header before executing the HTTP request Note: user name and password properties are not set in the request header and are case sensitive. No No No No Required No

Figure 272 shows an XML sample of the HTTP adapter request with a delete action. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 272 XML sample of the HTTP adapter request with a delete action
<http-adapter-request> <http-connection-properties /> <action>http://10.128.249.21:8080/httpclientoperations/HttpClientServlet</action> <use-ssl-certificate>false</use-ssl-certificate> <install-certificate>false</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <passphrase>changeit</passphrase> </http-adapter-request>

Chapter 4 Additional base adapters

355

HTTP adapter response with a delete action

HTTP adapter response with a delete action

Figure 271 shows an XML sample of the HTTP adapter response with a delete action. Figure 273 XML sample of the HTTP adapter response with a delete action
<httpAdapterResponse> <metadata> <status>success</status> </metadata> <status-line> <code>200</code> <reason>OK</reason> </status-line> <header-lines> <Server>Apache-Coyote/1.1</Server> <Content-Type>text/plain;charset=ISO-8859-1</Content-Type> <Content-Length>385</Content-Length> <Date>Mon, 05 Apr 2010 11:35:06 GMT</Date> </header-lines> <message-body><Html><Title>Testing Application for HTTP Adapter</Title> <Head></Head> <Title>Testing Application for HTTP Adapter</Title> <Head></Head> <Body>Hi, I am inside the doPost() Method of the EchoServlet</Body></Html></message-body> </httpAdapterResponse>

Specifying header fields in the HTTP adapter

This section explains how to specify header fields needed for an HTTP request using the HTTP adapter. The header fields are specified in the <http-connection-properties> element of the HTTP adapter request. The header fields are set in the request header of the HTTP request.

NOTE
The <user-name> and <password> elements are not set in the HTTP request header. They are used for basic authentication only.

356

BMC Atrium Orchestrator Base Adapters User Guide

Specifying header fields in the HTTP adapter

Figure 274 shows an XML sample of the HTTP adapter request with the header fields. Figure 274 XML sample of the HTTP adapter request with header fields
<httpadapterRequest> <action>http://www.someURL.com</action> <use-ssl-certificate></use-ssl-certificate> <install-certificate></install-certificate> <allow-unsigned-certificate></allow-unsigned-certificate> <passphrase></passphrase> <data-format>XHTML</data-format> <http-connection-properties> <user-name></user-name> <password></password> <Content-Type>text/html</Content-Type> <Connection>close</Connection> </http-connection-properties> </httpadapterRequest>

Table 122 describes the format of the HTTP adapter response based on the values provided in the <data-format> and <Content-Type> elements of the HTTP adapter request. Table 122 HTTP actions
<Content<data-format> Type> HTML TEXT or HTML, or */XML Perform JTidy on HTTP response Perform post processing Returned response is a well formed XML or XHTML Yes (Success) No (Failure) Not applicable HTTP response is added as TEXT to the <messagebody> element. The response is added as a child of the <messageNot applicable Not applicable body> element in the HTTP adapter Yes Not processed response. Not applicable Not applicable Yes Tags are eliminated (if present) The response is added as TEXT to the <non-xmldata-response> element. The <non-xml-dataresponse> element is added as a child of the <message-body> element in the HTTP adapter response.

Not applicable Not applicable Not applicable

XHTML

TEXT or HTML */XML TEXT or HTML */XML

XHTML XML XML

Chapter 4 Additional base adapters

357

JMS adapter

JMS adapter
The Java Message Service (JMS) adapter enables you to connect messaging systems to the Integration Engine or the PCK. The adapter supports the JMS specification 1.02b and 1.1. You can use the JMS adapter to send or receive an asynchronous message to a listed queue or topic on the JMS server. The JMS adapter belongs to the com.realops.adapter.jms Java package and consists of two JMS adapters: JMS actor adapter and JMS monitor adapter.

Before you begin 1 Create administered objects at the JMS provider (JMS interface) for
ConnectionFactory (an object that a client computer uses to create a connection to the JMS provider), queues (a staging area that contains messages), and topics (a mechanism for publishing messages) in the directory service designated for (Java Naming and Directory Interface (JNDI) lookup.

2 Review the JMS provider documentation to obtain a list of all the JAR files that are
necessary for a Java client. Copy all the specified JAR files to the $AO_HOME\tomcat\webapps\baocdp\WEB-INF\lib directory on the CDP server and all the peers that call the JMS adapter.

3 Verify that the JAR file of the JNDI service provider to be used is located in the
$AO_HOME\tomcat\webapps\baocdp\WEB-INF\lib directory on the CDP server and all the peers that use the JMS adapter. Java J2SE 1.6 (SDK) and later include the

following service providers:

s s s s

Lightweight Directory Access Protocol (LDAP) Common Object Services (COS) Naming Remote Method Invocation (RMI) Registry Domain Name System (DNS)

4 Verify the JNDI properties required to perform a name lookup using the service
provider. These properties are defined in the configuration node.

Prerequisites for the JMS adapter with IBM WebSphere MQ

Perform the following steps to copy the MQ client JAR files to the BMC Atrium Orchestrator peers on which the JMS monitor and actor adapters are enabled.

358

BMC Atrium Orchestrator Base Adapters User Guide

Prerequisites for the JMS adapter with IBM WebSphere MQ

To copy the MQ client JAR files to the BMC Atrium Orchestrator peers 1 Copy the .jar files from the IBM WebSphere MQ to the Atrium Orchestrator peer
enabled computer. The default path for the JAR files on the IBM WebSphere MQ is C:\Program
Files\IBM\WebSphere MQ\java\lib.

The path where the JAR files are to be copied on the Atrium Orchestrator peer enabled computer is AO_HOME\tomcat\webapps\baocdp\WEB-INF\lib.

2 You must copy the following JAR files:

com.ibm.mq.jar com.ibm.mq.jmqi.jar com.ibm.mqjms.jar connector.jar dhbcore.jar fscontext.jar jms.jar jndi.jar jta.jar ldap.jar providerutil.jar

To create the JMS .bindings file 1 Create an empty folder (for example, C:\MQJMSBindings) on the computer where
IBM WebSphere MQ is installed.

2 On the IBM WebSphere MQ Explorer page, drill down to IBM WebSphere MQ =>
JMS Administered Objects.

3 To create the default bindings file, right-click JMS Administered Objects, select Add
Initial Context, and browse to the empty folder created in step 1.

4 Navigate to JMS Administered Objects => Connection Factory. 5 Right-click Connection Factory and then select New => Connection Factory to create a
new Connection Factory. For example, BAOJMSConnection.

NOTE
Select Message Provider as WebSphereMQ, Type as Connection Factory, and Transport as MQ Client.

Chapter 4 Additional base adapters

359

Prerequisites for the JMS adapter with IBM WebSphere MQ

6 Change the value of Connection list to the IP address of the IBM WebSphere MQ
server.

7 Create corresponding JMS queues by selecting JMS .bindings file. To check the .bindings file for the localhost entries and copy it to the BMC Atrium Orchestrator peer 1 Open the .bindings file in a Notepad and search for localhost. Replace all instances
of localhost with the IP address of the IBM WebSphere MQ server.

2 Save the file and copy the directory containing the .bindings file to the root of the
BMC Atrium Orchestrator peer.

3 Restart the BMC Atrium Orchestrator peer to use the new IBM MQ client JAR files. 4 Configure the JMS actor and the JMS monitor adapter on Grid Manager using the
XMLs shown in Figure 275 on page 360 and Figure 276 on page 361. Figure 275 shows an XML sample for the JMS actor adapter configuration for using a IBM WebSphere MQ server. Figure 275 XML sample of the JMS actor adapter for the IBM WebSphere MQ server
<config> <jndi> <java.naming.factory.initial>com.sun.jndi.fscontext.RefFSContextFactory</java.naming.fact ory.initial> <java.naming.provider.url>file:///export/home/user2/CDP/MQJMSBindings</java.naming.provid er.url> </jndi> <user-name>username1</user-name> <password>password</password> <connection-factory>BAOJMSConnection</connection-factory> </config>

Figure 276 shows an XML sample for the JMS monitor adapter configuration for using the IBM WebSphere MQ server.

360

BMC Atrium Orchestrator Base Adapters User Guide

Prerequisites for the JMS adapter with IBM WebSphere MQ

Figure 276 XML sample of the JMS monitor adapter for the IBM WebSphere MQ server
<config> <jndi> <java.naming.factory.initial>com.sun.jndi.fscontext.RefFSContextFactory</java.naming.fact ory.initial> <java.naming.provider.url>file:///export/home/user2/CDP/MQJMSBindings/</java.naming.provi der.url> </jndi> <user-name>username</user-name> <password>password</password> <connection-factory>BAOJMSConnection</connection-factory> <queues> <queue> <destination-context-name>JMSMQTestRecieve</destination-context-name> <message-class>com.realops.adapter.jms.message.TextMessageProcessor</message-class> </queue> </queues> </config>

Figure 277 shows an XML sample of the JMS request for using the IBM WebSphere MQ server. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 277 XML sample of the JMS request for the IBM WebSphere MQ serverExample 1
<jmsRequest> <expiration>0</expiration> <priority>4</priority> <correlation-id>id-100</correlation-id> <jms-type>Actortype</jms-type> <delivery-mode>PERSISTENT</delivery-mode> <dest>JMSMQTestRecieve</dest> <body> <text>text message to JMS</text> </body> </jmsRequest>

Figure 278 on page 362 shows another XML sample of the JMS request using the IBM WebSphere MQ server. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 4 Additional base adapters

361

JMS actor adapter

Figure 278 XML sample of the JMS request for the IBM WebSphere MQ server Example 2
<jmsRequest> <expiration>0</expiration> <priority>4</priority> <correlation-id>id-100</correlation-id> <jms-type>Actortype</jms-type> <delivery-mode>PERSISTENT</delivery-mode> <dest>JMSMQTestRecieve</dest> <properties> <property> <name>Emp id</name> <value type="Integer">31100</value> </property> <property> <name>Emp Name</name> <value type="String">Mr. Bean</value> </property> <property> <name>Work hours</name> <value type="Float">38.87</value> </property> </properties> <body> <bytes>SGHGKJH87HCIU=</bytes> </body> </jmsRequest>

JMS actor adapter

The JMS actor adapter uses the JNDI properties specified to call ConnectionFactory and obtain a connection to the JMS provider. When a destination lookup name (queue or topic) and a message is passed, the JMS actor adapter sends the message to the specified computer. This adapter does not support multiple configuration nodes, but you can configure multiple JMS actor adapters within Grid Manager, each with a unique configuration node and adapter name. The <request-response-wait-timeout> element decides whether a response is synchronous or asynchronous.
s

In a synchronous request and response pattern, the adapter waits for a response if you specify a value in the <request-response-wait-timeout> element in the adapter request. In an asynchronous request and response pattern, the adapter does not wait for a response if you specify a value in the <request-response-wait-timeout> element. It closes the communication channel after sending the request.

362

BMC Atrium Orchestrator Base Adapters User Guide

JMS actor adapter

This section describes the configuration, request format, and response format of the JMS actor adapter:

JMS actor adapter configuration JMS actor adapter response JMS monitor adapter event

JMS monitor adapter configuration JMS actor adapter request

JMS actor adapter configuration

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-jms-actor[version] Default adapter name: JMSAdapter Table 123 describes the configuration elements for JMS adapter.

NOTE
The JMS actor adapter does not support form based adapter configuration at all. You would have to configure this adapter using the XML view. To configure the adapter, see Configuring the adapter on page 14.

Table 123 JMS actor adapter configuration node elements (part 1 of 2)

Element <jndi> <connectionfactory> <user-name> Description Contains JNDI properties to be set for a name lookup Specifies the lookup name for ConnectionFactory Specifies the user name for JMS providers authentication The requirements of the user's environment determine whether the <user-name> element is required. <password> Specifies the password that corresponds to the <user-name> provided The requirements of the user's environment determine whether the <password> element is required. <number-ofretries> Specifies the number of times the JMS adapter retries for a lost connection No to the JMS server Default value: 3 Conditional Required Yes Yes Conditional

Chapter 4 Additional base adapters

363

JMS actor adapter

Table 123 JMS actor adapter configuration node elements (part 2 of 2)

Element <retry-wait> Description Specifies the time (in milliseconds) the adapter waits before it retries a connection Default value: 5000 milliseconds (5 seconds) No <synchronous- Specifies the name of the destination queue or topic where the actor replyadapter waits (depending on the time defined in the adapter request) for a destination> response This element is used in a synchronous request and response pattern only. If the element is not specified, the actor adapter does not use a temporary destination (dynamic queue) for a response. Note: If the destination is a dynamic queue, ensure that no other consumer is listening to this destination. Required No

Figure 279 shows an XML template for the JMS actor adapter configuration. Figure 279 XML template of the JMS actor adapter configuration
<config> <jndi> <property name 1></property name 1> <property name 2></property name 2> ... </jndi> <connection-factory></connection-factory> <user-name></user-name> <password></password> <number-of-retries></number-of-retries> <retry-wait></retry-wait> <synchronous-reply-destination></synchronous-reply-destination> </config>

Figure 280 shows an XML sample for the JMS adapter configuration. Figure 280 XML sample of the JMS actor adapter configuration
<config> <jndi> <java.naming.factory.initial>org.apache.activemq.jndi.ActiveMQInitialContextFactory</j ava.naming.factory.initial> <java.naming.provider.url>tcp://10.254.1.113:61616</java.naming.provider.url> </jndi> <connection-factory>ConnectionFactory</connection-factory> <number-of-retries>3</number-of-retries> <retry-wait>2000</retry-wait> <synchronous-reply-destination>dynamicQueues/queue1.activemq.queue</synchronous-replydestination> </config>

364

BMC Atrium Orchestrator Base Adapters User Guide

JMS actor adapter

Figure 281 shows an XML sample for the JMS adapter configuration with a TIBCO
Enterprise Message Service (EMS).

Figure 281 XML sample for the JMS adapter configuration with a TIBCO EMS
<config> <jndi> <java.naming.factory.initial>com.tibco.tibjms.naming.TibjmsInitialContextFactory

</java.naming.factory.initial>
<java.naming.provider.url>tcp://host name or IP address:port</java.naming.provider.url> <java.naming.security.principal>bmc</java.naming.security.principal> <java.naming.security.credentials>bmcadmin</java.naming.security.credentials> </jndi> <connection-factory>QueueConnectionFactory</connection-factory> <user-name>bmc</user-name> <password>bmcadmin</password> <number-of-retries>3</number-of-retries> <retry-wait>2000</retry-wait> </config>

NOTE
The <java.naming.security.principal> element specifies the user name for JMS providers authentication. The <java.naming.security.credentials> element specifies the password that corresponds to the <java.naming.security.principal> provided.

JMS actor adapter request

The JMS actor adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. The JMS adapter supports the following types of messages:
s s s

TextMessage MapMessage BytesMessage

Chapter 4 Additional base adapters

365

JMS actor adapter

The messages support the following type of values in the <value> tag of the JMS adapter request:
s s s s s s s s

String Integer Float Long Short Boolean Byte Double

Table 124 describes the adapter request elements for JMS adapter. Table 124 Actor adapter request elements for JMS adapter (part 1 of 2)
Element <dest> Description Specifies the lookup name for the destination queue or topic This element does not support a temporary destination (dynamic queue or topic). <body> Contains the messages (of at least one type) to be sent Yes No <properties Contains the elements in <property> element > It must contain at least one <property> element. <reply-to> Specifies the JMSDestination name (queue or topic) to send a reply <expiration Specifies the JMSExpiration header property (a field that stores the > expiration time of the message) The expiration value is in milliseconds. <priority> Specifies the JMSPriority header property that defines the transmission priority levels for a message from 0 to 9, with 0 as the lowest priority and 9 as the highest No Required Yes

No No

<correlatio Specifies the JMSCorrelationID header property to link two messages n-id> together (For example, to link a given reply to a request) <jms-type> <deliverymode> Specifies the JMSType header property that contains a message type identifier that is set by the client computer

No No

Specifies the JMSDeliveryMode header property that defines the persistence No of a message Valid values: PERSISTENT, NON_PERSISTENT

<property>

Contains the property details for a message This element must have <name> and <value> tags as its elements There must be only one type of value in a <property> tag.

Conditional

<text>

Holds the messages in text or XML format

Conditional

366

BMC Atrium Orchestrator Base Adapters User Guide

JMS actor adapter

Table 124 Actor adapter request elements for JMS adapter (part 2 of 2)
Element <map Description Contains the map message data It has one or more <entry> elements. The value of the <name> element must be unique. <bytes> <requestresponsewaittimeout> Contains the bytes message data Specifies the time (in milliseconds) for which the actor adapter waits for a reply to the message If this element is present in the request with a valid value, the adapter sends the message synchronously. If the reply is received before the timeout duration, the adapter sends the next message. Otherwise, the adapter waits for the timeout duration, and then sends the next message. <character- Specifies the name of the Character set used to encode or decode the set> characters This parameter applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional No Required Conditional

Chapter 4 Additional base adapters

367

JMS actor adapter

Figure 282 shows an XML template for the JMS actor adapter request. Figure 282 XML template of the JMS actor adapter request
<jmsRequest> <reply-to></reply-to> <expiration></expiration> <priority></priority> <correlation-id></correlation-id> <jms-type></jms-type> <delivery-mode></delivery-mode> <dest></dest> <character-set>Shift_JIS</character-set> <request-response-wait-timeout></request-response-wait-timeout> <properties> <property> <name></name> <value type="Integer"></value> </property> <property> <name></name> <value type="String"></value> </property> . . <property> <name></name> <value type="Float"></value> </property> </properties> <body> <text>text message here</text> <map> <entry> <name></name> <value type="String"></value> </entry> <entry> <name></name> <value type="Integer"></value> </entry> . . <entry> <name></name> <value type="Float"></value> </entry> </map> <bytes></bytes> </body> </jmsRequest>

Figure 283 on page 369 shows an XML sample of the adapter request for the synchronous JMS actor adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

368

BMC Atrium Orchestrator Base Adapters User Guide

JMS actor adapter

Figure 283 XML sample of the synchronous JMS actor adapter request
<jmsRequest> <dest>dynamicQueues/queue2.activemq.queue</dest> <expiration>100</expiration> <priority>8</priority> <correlation-id>id-100</correlation-id> <jms-type>Actor type</jms-type> <request-response-wait-timeout>1000</request-response-wait-timeout> <reply-to>dynamicQueues/queue1.activemq.queue</reply-to> <properties> <property> <name>Emp id</name> <value type="Integer">31100</value> </property> <property> <name>Emp Nmae</name> <value type="String">Mr. Bean</value> </property> <property> <name>Work hours</name> <value type="Float">38.87</value> </property> </properties> <body> <bytes>First byte SGHGKJH87HCIU=</bytes> <bytes>Second byte gagfsagf627356#$$</bytes> </body> </jmsRequest>

Figure 284 on page 370 shows an XML sample of an asynchronous adapter request for the JMS actor adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 4 Additional base adapters

369

JMS actor adapter

Figure 284 XML sample of the asynchronous JMS actor adapter request
<jmsRequest> <dest>dynamicQueues/queue2.activemq.queue</dest> <reply-to>dynamicQueues/queue1.activemq.queue</reply-to> <properties> <property> <name>fl Work</name> <value type="Float">1000</value> </property> <property> <name>do Work</name> <value type="Double">1000</value> </property> <property> <name>Emp id</name> <value type="Integer">31100</value> </property> <property> <name>lo Work</name> <value type="Long">92233</value> </property> <property> <name>sh Work</name> <value type="Short">922</value> </property> <property> <name>Emp Name</name> <value type="String">Mr. Bean </value> </property> <property> <name>Transport</name> <value type="Boolean">false</value> </property> <property> <name>Transname</name> <value type="Byte">12</value> </property> </properties> <body> <text>This is to test one</text> <text>This is to test two</text> <text>This is to test three</text> </body> </jmsRequest>

JMS actor adapter response

Table 125 describes the JMS actor adapters asynchronous response elements. Table 125 JMS actor adapter response elements (asynchronous) (part 1 of 2)
Element <jms-response> <metadata> <status> Description Encloses the adapters response Contains the <status> elements Indicates the status of a command execution Valid values: success, error <execution-milliseconds> Specifies the time (in milliseconds) taken to execute a command

370

BMC Atrium Orchestrator Base Adapters User Guide

JMS actor adapter

Table 125 JMS actor adapter response elements (asynchronous) (part 2 of 2)

Element <error> Description Indicates the error message returned when the value of the <status> element is error When the value of the <status> element is success, this element is absent. <response-data> <JMSMessageID> Contains the <JMSMessageID> and the <error> elements Contains the message IDs for all the messages defined in the request The order of these elements is the same as the corresponding order of the messages listed in the original adapter request. <error> Specifies the error, if any, when sending a message

Figure 285 shows an XML template of an asynchronous adapter response for the JMS actor adapter. Figure 285 XML template of the JMS actor adapter asynchronous response
<jms-response> <metadata> <status></status> <execution-milliseconds></execution-milliseconds> </metadata> <response-data> <JMSMessageID></JMSMessageID> </response-data> </jms-response>

Table 126 describes the JMS actor adapters synchronous response elements. Table 126 JMS actor adapter response elements (synchronous) (part 1 of 2)
Element <jms-response <metadata <status Description Encloses the adapters response Contains the <status> elements Indicates the status of command execution Valid values: success, error <execution-milliseconds> <error> Specifies the time (in milliseconds) taken to execute a command Indicates the error message when the value of the <status> element is error When the value of the <status> element is success, this element is absent. <response-data> Contains the <JMSMessageID> and the <error> elements

Chapter 4 Additional base adapters

371

JMS actor adapter

Table 126 JMS actor adapter response elements (synchronous) (part 2 of 2)

Element <message> Description Contains information about the received response The order of these tags is the same as the corresponding order of the messages listed in the original adapter request. <error> <no-response> Occurs in the <response-data> element and specifies the error, if any, when sending a message Occurs in the <message> element if a response is not received in the specified time provided in the <request-response-waittimeout> element

Figure 286 shows an XML sample of a synchronous adapter response for the JMS actor adapter. Figure 286 XML sample of the JMS synchronous actor adapter response (part 1 of 2)
jms-response> <metadata> <status>success</status> <execution-milliseconds>828</execution-milliseconds> </metadata> <response-data> <message> <destination>queue1.activemq.queue</destination> <header> <JMSDeliveryMode>2</JMSDeliveryMode> <JMSExpiration>0</JMSExpiration> <JMSPriority>4</JMSPriority> <JMSMessageID>ID:realops-1081-12428879317650:14:2:1:1</JMSMessageID> <JMSTimestamp>1242968474890</JMSTimestamp> <JMSCorrelationID>ID:realops-1081-12428879317650:14:1:1:1</JMSCorrelationID> <JMSType /> <JMSRedelivered>false</JMSRedelivered> <JMSReplyTo>queue1.activemq.queue</JMSReplyTo>

372

BMC Atrium Orchestrator Base Adapters User Guide

JMS monitor adapter

Figure 286 XML sample of the JMS synchronous actor adapter response (part 2 of 2)
</header> <body> <Bytes>SGHGKJH87HCIU=</Bytes> </body> </message> <message> <destination>queue1.activemq.queue</destination> <header> <JMSDeliveryMode>2</JMSDeliveryMode> <JMSExpiration>0</JMSExpiration> <JMSPriority>4</JMSPriority> <JMSMessageID>ID:realops-1081-12428879317650:14:3:1:1</JMSMessageID> <JMSTimestamp>1242968475546</JMSTimestamp> <JMSCorrelationID>ID:realops-1081-12428879317650:14:1:1:2</JMSCorrelationID> <JMSType /> <JMSRedelivered>false</JMSRedelivered> <JMSReplyTo>queue1.activemq.queue</JMSReplyTo> </header> <body> <Bytes>SGHGKJH87HCIU=</Bytes> </body> </message> </response-data> </jms-response>

JMS monitor adapter

The JMS monitor adapter monitors queues and topics of a JMS provider for incoming MapMessage, BytesMessage, and TextMessage. This adapter does not support multiple configuration nodes, but you can configure multiple JMS monitor adapters within Grid Manager, each with a unique configuration node and adapter name. If the incoming messages are of any other type other than MapMessage, BytesMessage, and TextMessage, you need to customize the adapter and create a Java class to support the adapter. The Adapters Developer Guide provides details on customizing adapters.

NOTE
The JMS monitor adapter does not support temporary destinations (dynamic queues and topics).

This section describes the following configuration and event formats of the JMS monitor adapter:

JMS monitor adapter configuration

JMS monitor adapter event

Chapter 4 Additional base adapters

373

JMS monitor adapter

JMS monitor adapter configuration

Adapter type: ro-adapter-jms-monitor[version] Table 127 describes the configuration elements of the JMS monitor adapter.

NOTE
The JMS monitor adapter does not support form based adapter configuration at all. You would have to configure this adapter using the XML view. To configure the adapter, see Configuring the adapter on page 14.

Table 127 JMS monitor adapter configuration node elements (part 1 of 3)

Element <jndi> Description Contains JNDI properties that need to be set for a name lookup You can define multiple properties. <connectionfactory> <user-name> Specifies the lookup name for ConnectionFactory Specifies the user name for JMS providers authentication. The requirements of the user's environment determine whether the <user-name> element is required. <password> Specifies the password that corresponds to the <user-name> provided Conditional The requirements of the user's environment determine whether the <password> element is required. <of-retries> Specifies the number of times the JMS adapter retries for a lost connection to the JMS server Default value: 3 <retry-wait> Specifies the time (in milliseconds) the adapter waits before it retries for No a connection Default value: 5000 milliseconds (5 seconds) <client-id> Specifies the client ID to use for a durable subscription This element is required if the user's environment uses durable subscriptions. <queues> <queue> <destinationcontext-name> Contains the list of queues to be monitored Contains the details of a queue Contains the JNDI lookup name for a queue This element is required only when a <queue> element is defined. No No Conditional Conditional No Yes Conditional Required Yes

374

BMC Atrium Orchestrator Base Adapters User Guide

JMS monitor adapter

Table 127 JMS monitor adapter configuration node elements (part 2 of 3)

Element <maximummessages-persecond> <messageclass> Description Stops flooding the message queue This parameter throttles and stops swamping BMC Atrium Orchestrator with multiple threads when a large number of messages queue up. Specifies the fully qualified Java classname to be used for processing messages from a specific topic Default value: com.realops.adapter.jms. message.TextMessageprocessor Note: The <message-class> tag together with TextMessageProcesssor support the following class names:
s

Required No

No

com.realops.adapter.jms.message.MapMessageProcessor: supports MapMessage com.realops.adapter.jms.message.ByteMessageProcessor: supports ByteMessage com.realops.adapter.jms.message.GenericMessageProcessor: supports TextMessage, MapMessage, and ByteMessage No No Conditional

<topics> <topic> <destinationcontext-name>

Contains the list of topics to be monitored Contains the details of a topic Contains the JNDI lookup name for a topic This element is required only when a <topic> element is defined. In the absence of a <topic> element, this element is not required.

<messageclass>

Specifies the fully qualified (absolute) Java classname used for processing messages from a specific topic Default value: com.realops.adapter.jms. message.TextMessageprocessor Note: The <message-class> tag together with TextMessageProcesssor support the following class names:
s

No

com.realops.adapter.jms.message.MapMessageProcessor: supports MapMessage com.realops.adapter.jms.message.ByteMessageProcessor: supports ByteMessage com.realops.adapter.jms.message.GenericMessageProcessor: supports TextMessage, MapMessage, and ByteMessage

Chapter 4 Additional base adapters

375

JMS monitor adapter

Table 127 JMS monitor adapter configuration node elements (part 3 of 3)

Element <durablesubscribername> Description Specifies the durable subscription name (used to preserve messages published on a topic) for a topic This element is required only when the <client-id> element is defined. <characterset> Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Figure 287 shows an XML template for the JMS monitor adapter configuration. Figure 287 XML template of the JMS monitor adapter configuration
<config> <jndi> <property name 1></property name 1> <property name 2></property name 2> ... </jndi> <connection-factory></connection-factory> <user-name></user-name> <password></password> <of-retries></of-retries> <retry-wait></retry-wait> <client-id></client-id> <queues> <queue> <destination-context-name></destination-context-name> <maximum-messages-per-second></maximum-messages-per-second> <message-class></message-class> </queue> ... </queues> <topics> <topic> <destination-context-name></destination-context-name> <message-class></message-class> <durable-subscriber-name></durable-subscriber-name> </topic> ... </topics> <character-set></character-set> </config>

376

BMC Atrium Orchestrator Base Adapters User Guide

JMS monitor adapter

Figure 288 shows an XML sample of the JMS monitor adapter configuration. Figure 288 XML sample of the JMS monitor adapter configuration
<config> <jndi> <java.naming.factory.initial>org.apache.activemq.jndi.ActiveMQInitialContextFactory</java .naming.factory.initial> <java.naming.provider.url>tcp://10.254.1.113:61616</java.naming.provider.url> </jndi> <connection-factory>ConnectionFactory</connection-factory> <number-of-retries>3</number-of-retries> <retry-wait>2000</retry-wait> <queues> <queue> <destination-context-name>dynamicQueues/queue1.activemq.queue </destination-context-name> <maximum-messages-per-second>10</maximum-messages-per-second> <message-class>com.realops.adapter.jms.message.ByteMessageProcessor</message-class> </queue> </queues> <topics> <topic> <destination-context-name>dynamicTopics/topicnew</destination-context-name> <message-class>com.realops.adapter.jms.message.GenericMessageProcessor</messageclass> </topic> <topic> <destination-context-name>dynamicTopics/topicnewnew</destination-context-name> <message-class>com.realops.adapter.jms.message.GenericMessageProcessor</messageclass> </topic> </topics> <character-set>Shift_JIS</character-set> </config>

JMS monitor adapter event

Table 128 describes the elements for JMS monitor adapter event. Table 128 JMS monitor adapter event elements (part 1 of 2)
Element <message> <destination> <header> <JMSDeliveryMode> <JMSExpiration> <JMSPriority> <JMSMessageID> <JMSTimestamp> <JMSCorrelationID> <JMSType> <JMSReply-to> Description Contains the JMS message response Specifies the queue or topic for the message Contains the message header fields Specifies the delivery mode for the message Specifies the expiration time for the message Specifies the priority of the message Specifies the unique message identifier Specifies the time-stamp of the message Specifies the ID used to link one message with another Specifies the string identifying the contents of the message Specifies the destination name (name of the queue or topic) for sending a reply

Chapter 4 Additional base adapters

377

JMS monitor adapter

Table 128 JMS monitor adapter event elements (part 2 of 2)

Element <JMSRedelivered> <character-set> Description Indicates whether a message has been resent Specifies the character set used to decode characters for inbound encoded messages (only for ByteMessages type) The value of this parameter is the same as that set in each queue/topic in the JMS Monitor adapter configuration <character-set> element. Valid values: UTF-16, ISO-8859-1 (default), Shift_JIS <body> Contains the message body, in XML format

Figure 289 shows an XML sample for the JMS monitor adapter event. Figure 289 XML sample of the JMS monitor adapter event
<message> <destination> the queue/topic </destination> <header> <JMSDeliveryMode/> <JMSExpiration/> <JMSPriority/> <JMSMessageID/> <JMSTimestamp/> <JMSCorrelationID/> <JMSType/> <JMSReply-to/> <JMSRedelivered/> <properties> <property> <name>string</name> <value type="Integer">string</value> </property> . . <property> <name>string</name> <value type="Float">string</value> </property> </properties> </header> <body> <map> <entry> <name>Emp Name</name> <value type="String">Mr Bean.</value> </entry> <entry> <name>Emp id</name> <value type="Integer">1234</value> </entry> . . <entry> <name>Work Hours</name> <value type="Float">23.45</value> </entry> </map> <text>First message</text> <bytes>SHJHDGJHG=</bytes> </body> </message>

378

BMC Atrium Orchestrator Base Adapters User Guide

JMS monitor adapter

To use the data from a monitor adapter event in the triggered process, a Job Input Parameter, inputevent must be created on the Start activity of the process. The <data> element from the monitor adapter event populates this input. Figure 290 shows the XML sample response for the JMS monitor adapter event for BytesMessages type. Figure 290 XML sample of the JMS monitor adapter event message responseByte content only
<message> <destination>dynamicQueues/TestQueue</destination> <header> <JMSDeliveryMode>1</JMSDeliveryMode> <JMSExpiration>0</JMSExpiration> <JMSPriority>0</JMSPriority> <JMSMessageID>ID:Host-IP-1399-1258954714529-0:4:1:1:1</JMSMessageID> <JMSTimestamp>1258956950466</JMSTimestamp> <JMSCorrelationID /> <JMSType>Bytes</JMSType> <JMSRedelivered>false</JMSRedelivered> <character-set>UTF-16</character-set> <JMSReplyTo /> </header> <body> <Bytes>Bytes message with charset UTF-16</Bytes> </body> </message>

Figure 291 shows the XML sample response for the JMS monitor adapter event for mixed content type.

Chapter 4 Additional base adapters

379

Script adapter

Figure 291 XML sample of the JMS monitor adapter event message responsemixed content
<message> <destination>dynamicQueues/TestQueue</destination> <header> <JMSDeliveryMode>1</JMSDeliveryMode> <JMSExpiration>0</JMSExpiration> <JMSPriority>0</JMSPriority> <JMSMessageID>ID:Host-IP-1399-1258954714529-0:4:2:1:3</JMSMessageID> <JMSTimestamp>1258967812374</JMSTimestamp> <JMSCorrelationID /> <JMSType>Bytes</JMSType> <JMSRedelivered>false</JMSRedelivered> <character-set>UTF-16</character-set> <JMSReplyTo /> <properties> <property> <name>Work hours</name> <value type="Float">38.87</value> </property> <property> <name>Emp id</name> <value type="Integer">31100</value> </property> <property> <name>Emp Nmae</name> <value type="String">Mr. Bean</value> </property> </properties> </header> <body> <Bytes>SGHGKJH87HCIU=</Bytes> </body> </message>

Script adapter
The Script adapter executes Perl and Jython scripts. You can specify the initial values of variables in a script, and you can retrieve the values upon execution. This adapter does not support multiple configuration nodes, but you can configure multiple Script adapters within Grid Manager, each with a unique configuration node and an adapter name. For configuration instructions and to execute ActivePerl scripts in a Windows environment using a Script adapter, see Appendix B, Using ActivePerl scripts in a Windows environment.

NOTE
s

To ensure that processes using the Script adapter run successfully, check whether the Perl path designated in the Script adapter configuration exists on all the peers on which this adapter is enabled. Perl 5.8 or later is required. The Script adapter does not support Perl version 5.8.8 (except on the Windows operating system). It supports earlier and later versions of Perl 5.8.8. For example, Perl 5.8.5 and Perl 5.10.

380

BMC Atrium Orchestrator Base Adapters User Guide

Script adapter configuration

The information provided in this section applies to the use of the Script adapter in a Call Adapter activity in BMC Atrium Orchestrator Development Studio. See the BMC Atrium Orchestrator Development Studio User Guide for details on using the Script activity. The Script adapter supports three basic data structures, scalar (single values), lists (arrays), and maps (hashes).
s

Scalar variables: Designated using an XML element with the same name as the variable that contains a value that is set to the variable value. Do not include the $character used to designate Perl scalar values in the XML. Example: The Perl code $var1 = test is represented as <var1>test</var1> in the adapter request and response.

List variables: Designated using a parent and child relationship, where the parent defines the type, and the children contain the variable elements. Do not include the @ character used to designate Perl list variables in the XML. An XML sample for a list variable, var2, is as follows:

<var2 type="array"> <value>one</value> <value>two</value> </var2>

Map variables: Designated using a parent and child relationship, where the parent defines the type, and the children contain the variable elements. Do not include the % character used to designate Perl map variables in the XML. An XML sample for a map variable, var3 is as follows.

<var3 type="map"> <value key="one">1</value> <value key="two">2</value> </var3>

This section describes the configuration, request format, and response format of the Script adapter:

Script adapter configuration Script adapter response

Script adapter request

Script adapter configuration

Adapter type: ro-adapter-script[version]

Chapter 4 Additional base adapters

381

Script adapter request

Default adapter name: ScriptAdapter To configure the Script adapter, see Configuring the adapter on page 14. Table 129 describes the adapter configuration elements for the Script adapter that you can specify by 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. Table 129 Configuration node elements of the Script adapter
UI label Perl Path Element <perl-path> Description Specifies the fully qualified (absolute and unambiguous) path to the Perl executable Required Yes

Figure 292 shows an XML template for the Script adapter configuration. Figure 292 XML template of the Script adapter configuration
<config> <perl-path></perl-path> </config>

Figure 292 shows an XML sample for the Script adapter configuration. Figure 293 XML sample of the Script adapter configuration
<config> <perl-path>c:/Perl/bin/perl.exe</perl-path> </config>

Script adapter request

The Script adapter does not use an action. You must leave the adapters Action field blank while configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. You can include a <script> element that contains the entire script to be executed, or a <script-path> element that contains the path and the name of the script to be executed. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include empty elements in the adapter request because they might cause errors.

382

BMC Atrium Orchestrator Base Adapters User Guide

Script adapter request

Table 130 describes the adapter request elements for Script adapter. Table 130 Adapter request elements for Script adapter
Element Description Required Yes <script-type> Specifies the programming language in which the script is written Valid values: Perl, Jython <parameters> Specifies a group of key or value pairs that correspond to variables in the script you want to execute Do not include the Perl variable designators ($, %, and @) as variables in Perl scripts. <returnvalues> Specifies the variable names for the values returned on completion of a script execution No No

<script-path> Specifies the absolute path, including the script name, for the script to be Conditional executed This element is required only in the absence of a <script> element. It requires only one script designator element, either the <script-path> or the <script> element. This path must be the same for each peer that might be called to run a process that uses this Call Adapter activity. The script must be located in the same place on each peer. <script> Specifies the actual script to be executed This element is required only in the absence of a <script-path> element. It requires only one script designator element, either the <script-path> or the <script> element. If the script contains special XML characters, you must enclose the special character in the character data (CDATA). Conditional

Figure 294 shows an XML template for the Script adapter request with the <script> element. Figure 294 XML template of the Script adapter request with the <script> element
<script-request> <script-type></script-type> <parameters></parameters> <return-values></return-values> <script></script> </script-request>

Chapter 4 Additional base adapters

383

Script adapter request

Figure 295 shows an XML template for the Script adapter request with <scriptpath> element. Figure 295 XML template of the Script adapter request with the <script-path> element
<script-request> <script-type></script-type> <parameters></parameters> <return-values></return-values> <script-path></script-path> </script-request>

Figure 296 shows an XML sample of the Script adapter request with the <script> element as Jython. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 296 XML sample of the Script adapter request with the <script> element as Jython
<script-request> <script-type>Jython</script-type> <parameters> <a>3</a> <b>4</b> <d>5</d> <e>7</e> </parameters> <return-values> <value>c</value> <value>f</value> </return-values> <script><![CDATA[c=a+b;f=d+e]]></script> </script-request>

Figure 297 shows an XML sample of the Script adapter request with the <script> element as Perl. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 297 XML sample of the Script adapter request with the <script> element as Perl
<script-request> <script-type>Perl</script-type> <parameters> <var1>This is a test</var1> </parameters> <return-values> <value>out</value> </return-values> <script><![CDATA[($out)=$var1=~/\w+ \w+ \w+ (\w+)/;]]></script> </script-request>

Figure 298 on page 385 shows an XML sample of the Script adapter request with the
<script-path> element that contains the path and the name of the script to be

executed. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

384

BMC Atrium Orchestrator Base Adapters User Guide

Script adapter response

Figure 298 XML sample of the Script adapter request with <script-path> element
<script-request> <script-type>Jython or Perl</script-type> <parameters> <a>3</a> <b>4</b> <d>5</d> <e>7</e> </parameters> <return-values> <value>c</value> <value>f</value> </return-values> <script-path>/usr/scripts/named_script</script-path> </script-request>

Script adapter response

The Script adapter returns an adapter response that contains return values specified in the adapter request. The attribute for each value specifies the data type. Table 131 describes the Script adapter response elements. Table 131 Script adapter response elements
Element <return-values> <values> Description Contains the values returned from the Script adapter request Contains the type for each value requested

Figure 299 shows an XML sample for Script adapter response with the <script> element as Jython. Figure 299 XML sample of the Script adapter response with the script element as Jython
<return-values> <c type="scalar">7</c> <f type="scalar">12</f> </return-values>

Figure 300 shows an XML sample for Script adapter response with the <script> element as Perl. Figure 300 XML sample of the Script adapter response with the script element as Perl
<return-values> <out type="scalar">test</out> </return-values>

Chapter 4 Additional base adapters

385

SNMP actor adapter

SNMP actor adapter

The SNMP actor adapter contacts a remote SNMP device (such as computer, router, printer, and so on) and gathers the current values of one or more Managing Information Base (MIB) variable instances from the SNMP agent. The SNMP actor adapter supports SNMPv1 and SNMPv2c traps. The SNMP adapter does not require a configuration node, but you will need to configure the adapter in Grid Manager. This section describes the configuration, request format, and response format of the SNMP actor adapter:

SNMP actor adapter configuration SNMP actor adapter response with get action SNMP monitor adapter configuration SNMP actor adapter request with get action

SNMP actor adapter request Figure 304 shows an XML sample for SNMP adapter response with get action SNMP monitor adapter event SNMP actor adapter response with notification action

SNMP actor adapter configuration

Adapter type: ro-adapter-snmp-actor[version] Default adapter name: SNMPAdapter Figure 301 shows an XML template for the SNMP adapter configuration. Figure 301 XML template of the SNMP actor adapter configuration
<config/>

While the adapter does not require a configuration node, an XML tag, <config/> is required in the Properties field of Grid Manager for adapter configuration.

386

BMC Atrium Orchestrator Base Adapters User Guide

SNMP actor adapter request

SNMP actor adapter request

The SNMP actor adapter uses get or notification action. The SNMP actor adapter requests and responses are action-specific, the samples and the templates for each action are provided in the following sections. You must enter the action indicated in the adapters Action field in the Property panel of the Call Adapter activity. If an action is not provided for an SNMP actor adapter request, the default action, get is assumed. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

SNMP actor adapter request with get action

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not use empty elements in the adapter request because they might cause errors. Table 132 describes the SNMP adapter request elements with get action. Table 132 Adapter request elements for SNMP adapter with get action (part 1 of 2)
Element <host> <port> Description Required Specifies the host name or the IP address of the destination host computer Yes for the SNMP request Specifies the destination port for the SNMP request. Default value: 161 <community> <version> Specifies the SNMP community string (contains the statistics of a device) Specifies the SNMP version to use Valid values: 1 (default), 2c <retries> Specifies the number of times to retry a request. Default value: 2 <timeout> Specifies the number of seconds to wait before a retry attempt. Default value: 3 <oids> Contains the object identifier (OID), <oid> elements used to specify dynamic values This element is required, even if <oid> nodes are not defined. oid> Contains the name and value pair indicating the OID to the query This element is required if <name> and <value> elements are defined. Conditional Yes No No Yes No No

Chapter 4 Additional base adapters

387

SNMP actor adapter response with get action

Table 132 Adapter request elements for SNMP adapter with get action (part 2 of 2)
Element <name> Description Specifies the OID reference name used in the adapter response This element is required if an <oid> element is defined. <value> Specifies the OID for which information is returned This element is required if an <oid> element is defined. Conditional Required Conditional

Figure 302 shows an XML template for the SNMP adapter request with get action. Figure 302 XML template of the SNMP adapter request with get action
<snmp-adapter-request> <host></host> <port></port> <community></community> <version></version> <retries></retries> <timeout></timeout> <oids> <oid> <name></name> <value></value> </oid> ... </oids> </snmp-adapter-request>

Figure 303 shows an XML sample of the SNMP adapter request with get action. Figure 303 XML sample of the SNMP adapter request with get action
<snmp-adapter-request> <host>10.254.1.111</host> <port>161</port> <community>public</community> <oids> <oid> <name>Automation Testing</name> <value>.1.3.6.1.2.1.1.1.0</value> </oid> </oids> </snmp-adapter-request>

SNMP actor adapter response with get action

The SNMP actor adapter returns an adapter response that contains the OID name and response values returned from the adapter request. There can be multiple OID nodes in the response. Table 133 describes the elements of an SNMP actor adapter response to a request with get action.

388

BMC Atrium Orchestrator Base Adapters User Guide

SNMP actor adapter request with notification action

Table 133 Elements of an SNMP actor adapter response to a request with get action
Element <metadata> <status> Description Contains the summary information for the request Indicates the status of the request execution Valid values: success, error <error> Contains the error message if an interruption occurs during the execution of a request When the value of the <status> element is success, this element is absent. <executionmilliseconds> <oids> <oid> <name> <value> Specifies the duration of the request execution, in milliseconds Contains all the <oid> name and value pairs returned Contains the values returned from the SNMP adapter request Specifies the OID name requested in the adapter request Contains the result of the SNMP get action, performed for the requested OID

Figure 304 shows an XML sample for SNMP adapter response with get action Figure 304 XML sample of the SNMP adapter response with get action
<snmp-adapter-response> <metadata> <status>success</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> <oids> <oid> <name>name as defined in adapter request</name> <value>result of the SNMP Get for the requested OID</value> </oid> ... </oids> </snmp-adapter-response>

SNMP actor adapter request with notification action

The adapter format for the SNMP actor request with notification action is dependent on the SNMP version. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include empty elements in the adapter request as they might cause errors.

Chapter 4 Additional base adapters

389

SNMP actor adapter request with notification action

Table 134 describes the SNMP actor adapter request elements with notification action for SNMPv1 trap. Table 134 SNMP actor adapter request with notification action v1 SNMP trap elements
Element <targethost> <sourcehost> Description Required Specifies the host name or the IP address of the target computer that gets the Yes SNMP notification Specifies the host name or the IP address of the source computer that sends No the SNMP notification If you not provide this value, the host information for the peer on which the adapter request is being executed is used. <port> Specifies the target port for the SNMP notification Default value: 162 <community> Specifies the SNMP community string <enterprise Specifies the enterprise OID or string > <generic> <specific> <oids> Specifies the generic trap type Specifies the specific trap type (traps for specific MIBs) Contains the <oid> nodes used to specify dynamic values This element is required even if <oid> nodes are not defined. <oid> Contains the name and value pair for the OID notification This element is required if <name>, <value> and <type> elements are defined. <name> Specifies the OID name This element is required if an <oid> element is defined. <value> Specifies the OID value This element is required if an <oid> element is defined. <type> Specifies the OID data type This element is required if an <oid> element is defined. Valid values: STRING (default), INTEGER, OBJID, IPADDRESS, NETWORKADDRESS, COUNTER, GAUGE, UNSIGNED32, TIMETICKS, COUNTER64, NULLOBJ, OPAQUE Conditional Conditional Conditional Conditional Yes Yes Yes Yes Yes No

390

BMC Atrium Orchestrator Base Adapters User Guide

SNMP actor adapter request with notification action

Figure 305 shows an XML template of the SNMP adapter request with notification action for SNMPv1 trap. Figure 305 XML template of the SNMP adapter request with notification action for SNMPv1 trap
<snmp-adapter-request> <target-host></target-host> <source-host></source-host> <port></port> <community></community> <enterprise></enterprise> <generic></generic> <specific></specific> <oids> <oid> <name></name> <value></value> <type></type> </oid> </oids> </snmp-adapter-request>

Figure 306 shows an XML sample of the SNMP adapter request with notification action for SNMPv1 trap. Figure 306 XML sample of the SNMP actor adapter request with notification action for SNMPv1 trap
<snmp-adapter-request> <target-host>host name or IP address</target-host> <source-host>host name or IP address</source-host> <port>port number</port> <community>SNMP community</community> <enterprise>the enterprise OID or string</enterprise> <generic>generic trap type</generic> <specific>specific trap type</specific> <oids> <oid> <name>name the OID here</name> <value>actual OID</value> <type>valid OID data type</type> </oid> </oids> </snmp-adapter-request>

Chapter 4 Additional base adapters

391

SNMP actor adapter request with notification action

Table 135 describes the adapter request elements for the SNMP adapter with notification action for SNMP v2c trap. Table 135 Adapter request elements for the SNMP adapter with notification action for SNMPv2c trap
Element <targethost> <sourcehost> Description Element Specifies the host name or the IP address of the target computer that gets the Yes SNMP notification Specifies the host name or the IP address of the source computer that sends No the SNMP notification If you do not provide this value, the host information for the peer on which the adapter request is being executed is used. <port> Specifies the target port for the SNMP notification Default value: 162 <community> Specifies the SNMP community string <version> Specifies the SNMP version to be used Valid values: 1 (default), 2c <trap-oid> <oids> Specifies the object identifier (OID) of the trap or notification currently being Yes sent Contains the <oid> nodes used to specify dynamic values This element is required, even if <oid> nodes are not defined. <oid> Contains the name and value pair for the OID notification (alphanumeric and spaces) This element is required if <name>, <value>, and <type> elements are defined. <name> Specifies the OID name This element is required if an <oid> element is defined. <value> Specifies the OID value This element is required if an <oid> element is defined. <type> Specifies the OID data type This element is required, if an <oid> element is defined. Valid values: STRING, INTEGER, OBJID, IPADDRESS, NETWORKADDRESS, COUNTER, GAUGE, UNSIGNED32, TIMETICKS, COUNTER64, NULLOBJ, OPAQUE Default value: STRING Conditional Conditional Conditional Conditional Yes Yes Yes No

392

BMC Atrium Orchestrator Base Adapters User Guide

SNMP actor adapter response with notification action

Figure 307 shows an XML template of the SNMP adapter request with notification action for SNMPv2c trap. Figure 307 XML template of the SNMP adapter request with notification action for SNMPv2c trap
<snmp-adapter-request> <target-host></target-host> <source-host></source-host <port></port> <community></community> <version>2c</version> <trap-oid></trap-oid> <oids> <oid> <name></name> <value></value> <type></type> </oid> </oids> </snmp-adapter-request>

Figure 308 shows an XML sample of the SNMP adapter request with notification action. Figure 308 XML sample of the SNMP adapter request with notification action for SNMPv2c trap
<snmp-adapter-request> <target-host>10.10.75.82</target-host> <enterprise>1.3.6.1.4.1.1.1</enterprise> <generic>6</generic> <specific>1</specific> <port>8162</port> <community>public</community> <version>2c</version> <oids> <oid> <name>oid2</name> <value>.1.3.6.1.2.1.1.1.0</value> </oid> <oid> <name>oid2</name> <value>.1.3.6.1.2.1.1.1.0</value> </oid> </oids> </snmp-adapter-request>

SNMP actor adapter response with notification action

For both, v1 and v2c version SNMP traps, the SNMP actor adapter returns an adapter response that contains the summary information for the adapter request.

Chapter 4 Additional base adapters

393

SNMP monitor adapter

Table 136 describes the elements of an SNMP actor adapter response to a request with notification action. Table 136 Elements of an SNMP actor adapter response to a request with notification action
Element <metadata> <status> Description Contains the summary information of the request Indicates the status of the request execution Valid values: success, error <error> Contains the error message if an interruption during the execution of a request When the value of the <status> element is success, this element will not be present. <executionmilliseconds> Specifies the duration of the request execution, in milliseconds

Figure 309 shows an XML sample for the SNMP adapter response with notification action. Figure 309 XML sample response of the SNMP adapter with notification action
<snmp-adapter-response> <metadata> <status>success</status> <error>Present only with status of 'error'</error> <execution-milliseconds>value</execution-milliseconds> </metadata> </snmp-adapter-response>

SNMP monitor adapter

The SNMP monitor adapter receives traps from external systems, (for example, a source server), and forwards these traps to the foundation system, (for example, a target server) in a known XML format. The SNMP monitor adapter supports SNMPv1 and SNMPv2c traps. This adapter does not support multiple configuration nodes, but you can configure multiple SNMP monitor adapters within Grid Manager, each with a unique configuration node and adapter name.

NOTE
If the SNMP monitor adapter or the SNMP-based application adapter is configured with a port number less than 1024, you must ensure that the peer is configured with administrator or root privileges. This is a prerequisite for operating systems other than Windows.

394

BMC Atrium Orchestrator Base Adapters User Guide

SNMP monitor adapter configuration

This section describes the following configuration and event formats of the SNMP monitor adapter:

SNMP monitor adapter configuration

SNMP monitor adapter event

SNMP monitor adapter configuration

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-snmp-monitor[version] To configure the SNMP monitor adapter, see Configuring the adapter on page 14. Table 137 describes the adapter configuration elements for the SNMP monitor adapter that you can specify by 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. Table 137 SNMP monitor adapter configuration node elements
UI label Port Version Element <port> <version> Description Specifies the port of the source computer to listen for SNMP traps Specifies the SNMP version Specifies the directory location for SNMP MIBs Note: To ensure that processes using the SNMP monitor adapter run successfully, the <mibsdirectory> element must exist on all the peers on which this adapter is enabled. If you define an invalid path, the adapter goes into an error state. Required Yes Yes No

Mibs Directory <mibsdirectory>

Figure 310 XML template of the SNMP monitor adapter configuration

<config> <port></port> <version></version> <mibs-directory></mibs-directory> </config>

Chapter 4 Additional base adapters

395

SNMP monitor adapter event

SNMP monitor adapter event

The elements contained in the SNMP monitor event are different, based on the value defined for the <mibs-directory> element in the adapter configuration. Table 138 describes the elements of the SNMP monitor adapter event with <mibsdirectory> element defined. Table 138 SNMP monitor adapter event elements with the <mibs-directory> element defined
Element <host> <sysuptime> Description Specifies the host computer that generated the trap Specifies the time at which the trap was generated, expressed in 1/100 seconds from the start of the application that generated the trap Specifies the enterprise OID or STRING This element is used for v1 traps only; it is empty for v2c traps. <trap-type> <varbinds> <varbind> <oid> <name> <value> Specifies the type of trap string Contains the <varbind> elements Contains the details of an incoming trap Specifies the OID for the incoming trap Specifies the OID reference name for the incoming trap Specifies the OID value for the incoming trap

<enterprise>

Figure 311 shows an XML sample of the SNMP monitor adapter event with <mibsdirectory> defined.

Figure 311 XML sample of the SNMP monitor adapter event with <mibs-directory> element defined
<trap> <host>local host</host> <sysuptime>value in 1/100 seconds</sysuptime> <enterprise>text</enterprise> <trap-type>text</trap-type> <varbinds> <varbind> <oid>text</oid> <name>text</name> <value>text</value> </varbind> </varbinds> </trap>

To use the data from the monitor adapter event in a triggered process, a Job Input Parameter, inputevent, must be created on the Start activity of the process. The <data> element from the monitor adapter event populates this input.

396

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter

Table 139 describes the elements of the SNMP monitor adapter event without the definition of the <mibs-directory> element. Table 139 SNMP monitor adapter without <mib-directory> definition elements
Element <host> <sysuptime> Description Specifies the host computer that generated the trap Specifies the time at which the trap was generated, expressed in 1/100 seconds from the start of the application that generated the trap Specifies the enterprise OID or STRING This element is used for v1 traps only; it is empty for v2c traps. <generic-trap-type> <varbinds> <varbind> <oid> <value> Specifies the generic trap type Contains the <varbind> elements Contains the details of an incoming trap Specifies the OID for the incoming trap Specifies the OID value for the incoming trap <specific-trap-type> Specifies the specific trap type

<enterprise>

Figure 312 shows an XML sample of the SNMP monitor adapter event without the
<mibs-directory> element defined.

Figure 312 XML sample of the SNMP monitor adapter event without the <mibsdirectory> element defined
<trap> <host>10.10.255.255</host> <sysuptime>value in 1/100 seconds</sysuptime> <enterprise>text</enterprise> <generic-trap-type>text</generic-trap-type> <specific-trap-type>text</specific-trap-type> <varbinds> <varbind> <oid>text</oid> <value>text</value> </varbind> </varbinds> </trap>

SQL actor adapter

The SQL actor adapter provides the ability to interact with an SQL database using Java Database Connectivity (JDBC). You can configure multiple SQL actor adapters within Grid Manager, each with a unique configuration node and adapter name with the <configs> tag.

Chapter 4 Additional base adapters

397

IMW Support

The SQL actor adapter supports simple and parameterized statements. The adapter configuration does not depend on the statement type. You must place the driver for the SQL database, to which this adapter connects, in the $AO_HOME/lib/shared directory on each peer, on which the adapter is enabled. Each peer is restarted after you place the .JAR file for the driver. This section describes the configuration, request format, and response format of the SQL actor adapter:

SQL actor adapter configuration SQL actor adapter responseStandard SQL actor adapter requestStandard

SQL actor adapter request SQL actor adapter requestParameterized Statement SQL actor adapter response Parameterized Statement

IMW Support
The SQL actor adapter supports the Integration Mapping Wizard (IMW) feature. IMW uses simple, form-based inputs to construct XML-based inputs for wrappers. IMW abstracts the difficulty involved in writing complex XML inputs for wrappers, hence, you can use IMW to execute workflows in a user-friendly way. You can use the Integration Mapping Activity of BMC Atrium Orchestrator Development Studio and the IMW to perform basic operations like insert, update, delete, and select using the SQL actor adapter. For more information about Integration Mapping activity and IMW, see the BMC Atrium Orchestrator Development Studio User Guide.

SQL actor adapter configuration

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. You can configure the SQL adapter for multiple targets. The <configs> tag helps you configure multiple targets. Adapter type: ro-adapter-sql-actor[version] Default adapter name: SQLAdapter You can define the URL for an SQL query in the following ways:

398

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter configuration

Define the target, port, subprotocol, database, and any parameter as elements in the configuration, allowing the process to form the URL

The following sample is an excerpt from the SQL actor adapter configuration that depicts method one of defining the URL. You need supporting elements to form the complete configuration. Figure 313 XML sample of method one for defining a URL
<target>target1</target> <port>port1</port> <subprotocol>oracle:thin</subprotocol> <database>database1</database> <parameters> <param1>abc</param1> <param2>xyz</param2> </parameters>

Define the complete URL, including parameters, in a single element in the configuration

The following sample is an excerpt from the SQL actor adapter configuration that depicts method two to define the URL. You need supporting elements to form the complete configuration. Figure 314 XML sample of method two for defining a URL
<url>jdbc:oracle:thin:@target1:port1:database1?param1=abc&param2=xyz</url>

To configure the SQL actor adapter, see Configuring the adapter on page 14. Table 140 describes the adapter configuration elements for the SQL actor adapter that you can specify by 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. Table 140 SQL actor adapter configuration node elements (part 1 of 5)
UI label None Url Element <configs> <url> Description Configures SQL actor adapter on multiple target computers Specifies the complete connection URL for the target database If this value is not provided, <target>, <port>, <subprotocol>, <database>, and <parameters> elements must be provided (as needed) so that the process can create the URL. Required No No

Chapter 4 Additional base adapters

399

SQL actor adapter configuration

Table 140 SQL actor adapter configuration node elements (part 2 of 5)

UI label Target Element <target> Description Specifies the host name or the IP address of the database server This element is required in the absence of the <url> element. Port <port> Specifies the port on which the database server listens Conditional The requirements for the JDBC driver specified in the <driver> element determine whether the <port> element is required. This element is not used if the <url> element is provided. User Name <user-name> Specifies the user name to be used for database authentication The database requirements in the user's environment determine whether the <user-name> element is required. Password <password> Specifies the password that corresponds to the <user-name> element provided The database requirements in the user's environment determine whether the <password> element is required. Subprotocol <subprotocol Specifies the driver-specified subprotocol used to > build the connection URL The adapter prepends jdbc: to the value provided. This element is required in the absence of the <url> element.
s s

Required Conditional

Conditional

Conditional

Conditional

Format: database type:subprotocol Sample values: sybase:Tds, oracle:thin No

Statement Terminator

<statementterminator>

Specifies the special character used as a termination value for SQL statements Do not use this element when communicating with Oracle databases.

Database

<database>

Specifies the name of the database to which the adapter connects The database requirements determine whether the name of the database is a required element. This element is not used if a <url> element is provided.

Conditional

400

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter configuration

Table 140 SQL actor adapter configuration node elements (part 3 of 5)

UI label Driver Element <driver> Description Specifies the fully qualified (absolute) JDBC driver classname Sample values:
s s

Required Conditional

com.sybase.jdbc3.jdbc.SybDriver oracle.jdbc.driver.OracleDriver

Max Wait

<max-wait>

Specifies the maximum time (in milliseconds) to wait No before timing out, when establishing a connection to a database Default value: 60,000 milliseconds (1 minute)

None

<parameters> Specifies the JDBC connection parameters The elements contained in the <parameters> element represent key and value pairs that are appended to the end of the JDBC URL that is created. Format: <parameter-elementname>value</parameter-element-name> This element is not used when the <url> element is present. The URL must contain any necessary parameters.

No

Max Connection Idle Time Millis Min Connection Idle Time Millis Evictor Idletime Millis

<maxconnectionidle-timemillis> <minconnectionidle-timemillis> <evictoridle-timemillis>

Specifies the maximum time (in milliseconds) that a connection can remain idle before it is closed Default value: 300,000 (5 minutes)

No

Specifies the minimum time (in milliseconds) that a No connection can remain idle before being evaluated for termination Specifies the frequency (in milliseconds) in which a thread used to close idle connections runs Default value: 60,000 milliseconds (1 minute) No

Max Active Connections

<max-active- Specifies the maximum number of connections connections> allowed at any time in the connection pool Default value: 10

No

Chapter 4 Additional base adapters

401

SQL actor adapter configuration

Table 140 SQL actor adapter configuration node elements (part 4 of 5)

UI label Initial Active Connections Element Description Required <initialSpecifies the minimum number of connections created No activeduring adapter startup connections> The poolable API of Apache software does not support this feature. However, the BasicDataSource (non-poolable-version), supports this feature. Default value: 2 Max Idle Connections <max-idleSpecifies the maximum number of idle connections connections> allowed at any time Default value: 5 Min Idle Connections <min-idleSpecifies the minimum number of idle connections connections> allowed at any time Default value: 0 Validate Query <validatequery> Specifies a query statement used to validate the connection This element is required in the presence of the <validate-connections-on-return> or <validate-idle-connections> element. Default value: None Validate Connections On Return <validateIndicates whether a connection is validated when it is No connections- returned to the pool on-return> The <validate-query> element must be present to use this feature. Valid values: true, false (default) With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. Validate Idle Connections No <validateIndicates whether periodic checks are done on idle idleconnections in the pool (set of connections) connections> The <validate-query> element must be present to use this feature. Valid values: true, false (default) With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. Conditional No No

402

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter configuration

Table 140 SQL actor adapter configuration node elements (part 5 of 5)

UI label Element Description Required Ktgt Cache File <ktgt-cache- Specifies the location of a valid Kerberos Ticket No file> Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cachefile>/tmp/krb5cc_0</ktgt-cache-file> Krb Service Principal <krbserviceprincipal> Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</kr b-service-principal> Conditional

Figure 315 shows an XML sample for the SQL actor adapter configuration without a URL. Figure 315 XML sample of the SQL actor adapter configuration without a URL
<configs> <config name = "mysql"> <target>localhost</target> <port>3306</port> <user-name>root</user-name> <password>root123</password> <subprotocol>mysql</subprotocol> <database>test</database> <driver>com.mysql.jdbc.Driver</driver> </config> <config name = "oracle"> <target>10.254.1.76</target> <port>1521</port> <user-name>system</user-name> <password>system</password> <subprotocol>oracle:thin</subprotocol> <database>ORCL</database> <driver>oracle.jdbc.driver.OracleDriver</driver> </config> <config name = "mysql111"> <target>localhost</target> <port>3306</port> <user-name>firstuser</user-name> <password>firstuser</password> <subprotocol>mysql</subprotocol> <database>firstuser</database> <driver>com.mysql.jdbc.Driver</driver> </config> </configs>

Chapter 4 Additional base adapters

403

SQL actor adapter configuration

Figure 316 shows an XML sample for the SQL actor adapter configuration with a URL. Figure 316 XML sample of the SQL actor adapter configuration with a URL
<configs> <config name = "mysql"> <url>jdbc:mysql://localhost:3306/test</url> <user-name>root</user-name> <password>root123</password> <driver>com.mysql.jdbc.Driver</driver>5 <max-wait>1200</max-wait> </config> <config name = "oracle"> <url>jdbc:oracle:thin:@10.254.1.76:1521:bcas</url> <user-name>system</user-name> <password>system</password> <driver>oracle.jdbc.driver.OracleDriver</driver> <max-wait>1200</max-wait> </config> <config name = "mysql111"> <url>jdbc:mysql://localhost:3306/firstuser</url> <user-name>firstuser</user-name> <password>firstuser</password> <driver>com.mysql.jdbc.Driver</driver> <max-wait>1200</max-wait> </config> </configs>

Figure 317 shows an XML sample for the SQL actor adapter configuration with Sybase Kerberos Authentication. Figure 317 XML sample of an SQL actor adapter configuration for Sybase Kerberos Authentication
<config name = "sybasedb"> <target>10.128.248.105</target> <url>jdbc:sybase:Tds:10.128.248.105:5000/MASTER</url> <user-name>sa</user-name> <password /> <driver>com.sybase.jdbc3.jdbc.SybDriver</driver> <database>master</database> <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cache-file> <krb-service-principal>REALOPSLINUX1@SYNAPSE.COM</krb-service-principal> </config>

You can also have an empty configuration as shown in Figure 318. Figure 318 XML sample of an SQL actor adapter with an empty configuration
<config/>

404

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter request

SQL actor adapter request

The SQL actor adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call Adapter activity in BMC Atrium Orchestrator Development Studio. The samples for the request and response for each option are provided in the following sections. Following are the options that you can use to define SQL actor adapter requests:
s

Standard: Requests that use a single <action> element that contains an SQL statement. This statement can be wrapped in CDATA to handle XML special characters, but the data values can not contain characters that the target database considers as special characters. Parameterized Statements: Requests that can be used to execute SQL statements against one or more data sets. The statements can contain bind variables as needed. JDBC handles any data values containing characters considered as special characters (by the target database). These statements support transactions.

SQL actor adapter requestStandard

The adapter request uses a single element, <action>, that contains the SQL statement to be executed. You can define one <action> element only for each Standard SQL adapter request. If the SQL statement contains a special XML character, the statement must be enclosed in CDATA. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. Figure 319 shows a standard (legacy) XML sample for the SQL actor adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 319 XML sample of the SQL standard actor adapter request (legacy)
<sqladapterRequest> <action>select * from table1</action> </sqladapterRequest>

The adapter request uses the <targets> element to configure multiple SQL adapter target computers. Figure 320 shows a standard (dynamic) XML sample for the SQL actor adapter request. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 4 Additional base adapters

405

SQL actor adapter requestStandard

Figure 320 XML sample of the SQL standard actor adapter request (dynamic)
<sqlAdapterRequest> <targets> <target name="ARSA"> <host>10.128.248.78</host> <port>1521</port> <user-name>bmcadmin</user-name> <password>abc123</password> <subprotocol>oracle:thin</subprotocol> <database>testdb</database> <driver>oracle.jdbc.driver.OracleDriver</driver> </target> </targets> <action>select PERSON_ID, LAST_NAME from PERSON</action> </sqlAdapterRequest>

NOTE
You can also specify targets (dynamically) that are not in the adapter configuration.

Figure 321 on page 406 shows a standard XML sample for the SQL actor adapter request with Sybase Kerberos Authentication. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 321 XML sample of the SQL standard actor adapter request with Sybase Kerberos Authentication.
<sqlAdapterRequest> <targets> <target name="SybaseKrb"> <url>jdbc:sybase:Tds:10.128.248.105:5000/MASTER</url> <user-name>sa</user-name> <driver>com.sybase.jdbc3.jdbc.SybDriver</driver> <password /> <database>master</database> <ktgt-cache-file>C:\\Program Files\\Mit\\Kerberos\\bin\\krb5cc_bmcadmin</ktgt-cachefile> <krb-service-principal>REALOPSLINUX1@SYNAPSE.COM</krb-service-principal> </target> </targets> <action>SELECT * FROM spt_monitor</action> </sqlAdapterRequest>

Table 141 describes the adapter request elements for the SQL standard actor adapter. Table 141 Adapter request elements for SQL standard actor adapter (part 1 of 2)
Element <action> <targets> <target> Description Specifies the SQL statement to be issued to the database Holds the <target> elements Provides the definitions for dynamic targets at run time Required Yes No No

406

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter responseStandard

Table 141 Adapter request elements for SQL standard actor adapter (part 2 of 2)
Element <ktgt-cachefile> Description Required Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) No to obtain a connection through the Kerberos tunnel Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile>

SQL actor adapter responseStandard

Table 142 displays the standard actor adapter response elements. Table 142 SQL standard actor adapter response elements
Element <queryExecuted> <responseRowCount> Description Syntax of the query defined in the adapter request Number of rows returned in the response

<responseColumnCount Number of columns returned for each row > <row> <column> Values returned for one row of the query Column name and value returned in the response

Figure 322 illustrates an XML sample of the adapter response for the SQL actor adapter (legacy). Figure 322 XML sample of the SQL standard actor adapter response (legacy)
<sqlAdapterResponse> <row> <column name = "description" label = "description">my new value</column> </row> <metadata> <queryExecuted>select * from test</queryExecuted> <execution-milliseconds>4562</execution-milliseconds> <responseRowCount>1</responseRowCount> <responseColumnCount>1</responseColumnCount> <status>success</status> </metadata> </sqlAdapterResponse>

For a Standard dynamic request, for multiple configurations, if you provide the <target> tag, you observe the <target-outputs> tag in the corresponding response.

Chapter 4 Additional base adapters

407

SQL actor adapter responseStandard

Table 143 displays the additional dynamic adapter response elements that are included with the target-output response element. Table 143 SQL standard actor adapter response elements (dynamic)
Element <target-metadata> <database> <database-vendor> <status> Description Contains target level summary information Specifies the database name Specifies the database vendor name Indicates the status of the request Valid values: success, error <error> Contains the error message if a statement level error occurs When the value of the <status> element is success, this element is absent.

408

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter responseStandard

Figure 323 illustrates an XML sample of the dynamic adapter response for the SQL actor adapter. Figure 323 XML sample of the SQL standard actor adapter response (dynamic) (part 1 of 2) (part 1 of 2)
<sqlAdapterResponse> <metadata> <status>success</status> </metadata> <targets-output> <target-output name="ARSA"> <target-metadata> <database>testdb</database> <database-vendor>Oracle</database-vendor> <status>success</status> </target-metadata> <action-response> <row> <column label="PERSON_ID" name="PERSON_ID">900</column> <column label="LAST_NAME" name="LAST_NAME">Malhotra</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">800</column> <column label="LAST_NAME" name="LAST_NAME">DUGAR</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">500</column> <column label="LAST_NAME" name="LAST_NAME">keswani</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">600</column> <column label="LAST_NAME" name="LAST_NAME">Chugh</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">800</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">400</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">300</column> <column label="LAST_NAME" name="LAST_NAME">maduri</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">700</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">800</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row>

Chapter 4 Additional base adapters

409

SQL actor adapter responseStandard

Figure 323 XML sample of the SQL standard actor adapter response (dynamic) (part 2 of 2) (part 2 of 2)
<row> <column <column </row> <row> <column <column </row> label="PERSON_ID" name="PERSON_ID">400</column> label="LAST_NAME" name="LAST_NAME">gupta</column> label="PERSON_ID" name="PERSON_ID">300</column> label="LAST_NAME" name="LAST_NAME">maduri</column>

<row> <column label="PERSON_ID" name="PERSON_ID">100</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">200</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">300</column> <column label="LAST_NAME" name="LAST_NAME">maduri</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">200</column> <column label="LAST_NAME" name="LAST_NAME">gupta</column> </row> <row> <column label="PERSON_ID" name="PERSON_ID">300</column> <column label="LAST_NAME" name="LAST_NAME">maduri</column> </row> <metadata> <queryExecuted>select PERSON_ID, LAST_NAME from PERSON</queryExecuted> <execution-milliseconds>29</execution-milliseconds> <responseRowCount>16</responseRowCount> <responseColumnCount>2</responseColumnCount> <status>success</status> </metadata> </action-response> </target-output> </targets-output> </sqlAdapterResponse>

410

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter requestParameterized Statement

Figure 324 illustrates an XML sample of the adapter response for the SQL actor adapter with Sybase Kerberos Authentication. Figure 324 XML sample of the SQL standard actor adapter response with Sybase Kerberos Authentication
<sqlAdapterResponse> <metadata> <status>success</status> </metadata> <targets-output> <target-output name="10.128.248.105"> <target-metadata> <database>master</database> <database-vendor>Adaptive Server Enterprise</database-vendor> <status>success</status> </target-metadata> <action-response> <row> <column name="First_name" label="First_name">Ritu</column> <column name="Last_name" label="Last_name">Chugh</column> <column name="Address" label="Address">West Delhi</column> <column name="City" label="City">New Delhi</column> <column name="State" label="State">De</column> <column name="Zip" label="Zip">110019</column> <column name="Phone" label="Phone">90097130</column> </row> <row> <column name="First_name" label="First_name">Rajat</column> <column name="Last_name" label="Last_name">Arora</column> <column name="Address" label="Address">West Delhi</column> <column name="City" label="City">Delhi</column> <column name="State" label="State">De</column> <column name="Zip" label="Zip">110089</column> <column name="Phone" label="Phone">623568935</column> </row> <metadata> <queryExecuted>select * from Rolodex</queryExecuted> <execution-milliseconds>76</execution-milliseconds> <responseRowCount>2</responseRowCount> <responseColumnCount>7</responseColumnCount> <status>success</status> </metadata> </action-response> </target-output> </targets-output> </sqlAdapterResponse>

SQL actor adapter requestParameterized Statement

This adapter request is used to execute SQL statements against one or more data sets. One or more statements might be executed in a single adapter request. Each statement can contain bind variables. The data values for these variables are escaped using Java JDBC's implicit special character escaping feature. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

Chapter 4 Additional base adapters

411

SQL actor adapter requestParameterized Statement

BMC recommends that you do not include empty non-required elements in the adapter request as they might cause errors. The following sample depicts a query performed for two different parameters. The parameters are indicated in the query statement with a ?. Each parameter value is provided in a parameter set, along with the data type for the value. Table 144 describes the adapter request elements for the SQL actor adapter with the parameterized statements. Table 144 SQL parameterized statement actor adapter request elements (part 1 of 2)
Element Description Required <enableDetermines whether to use the transaction for all the SQL queries defined No transaction> in the adapter request Valid values: true, false (default) <statements> Contains the <statement> elements <statement> <query> Contains the query and any parameter sets Specifies the SQL query to be executed This element is required if the value in the<query> element contains a ? character for bind variable substitution. You can use a ? to indicate the location for bind variable substitution. <parametersets> Contains the <parameter-set> elements used as bind variables This element is required if the value in the <query> element contains a ? character for bind variable substitution. <parameterset> Contains the <parameter> elements This element is required if the value in the <query> element contains a ? character for bind variable substitution. <parameter> Contains the <data-type> and <value> elements for each bind variable in the <query> element This element is required if the value in the <query> element contains a ? character for bind variable substitution. <data-type> Specifies the type of data the statement must expect This element is required if the value in the <query> element contains a ? character for bind variable substitution. Valid values: BIGINT, BOOLEAN, CHAR, DATE, DOUBLE, FLOAT, INTEGER, NULL, NUMERIC, TIMESTAMP, VARCHAR <value> Specifies the input value for a bind variable This element is required if the value in the <query> element contains a ? character for bind variable substitution. <targets> Holds the <target> elements No Conditional Conditional Conditional Conditional Conditional Yes Yes Yes

412

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter requestParameterized Statement

Table 144 SQL parameterized statement actor adapter request elements (part 2 of 2)
Element <target> Description Provides definitions for dynamic targets at run time Required No No

<enableDecides whether to use a transaction for all SQL queries defined in the transaction> adapter request Valid values: true, false (default)

NOTE
s s s

Transaction support is applicable to Data Manipulation Language (DML) statements only. Transaction does not support Standard SQL adapter requests. The SQL adapter does not support transactions when: The <enable-transaction> tag is not included in the adapter request or has an invalid value. The value of the <enable-transaction> tag is set to false.

Figure 325 shows an XML sample of the legacy adapter request for the SQL actor adapter with a parameterized statement. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 325 XML sample of the SQL actor adapter request with a parameterized statement (legacy)
<sql-adapter-request> <statement> <query>select ID, NAME, DEPT, EMAIL From employee Where DEPT = ?</query> <parameter-sets> <parameter-set> <parameter> <data-type>VARCHAR</data-type> <value>BMC</value> </parameter> </parameter-set> </parameter-sets> </statement> </sql-adapter-request>

For a Parameterized statement dynamic request, if you provide the <targets> tag in the request for multiple target computers, you observe the <target-outputs> tag in the corresponding response. Figure 326 shows an XML sample of the dynamic adapter request for the SQL actor adapter with the parameterized statement.

Chapter 4 Additional base adapters

413

SQL actor adapter requestParameterized Statement

Figure 326 XML sample of the SQL actor adapter request with a parameterized statement (dynamic)
<sql-adapter-request> <targets> <target name = "mysql"/> <target name = "oracle1"> <host>localhost</host> <port>3306</port> <user-name>root</user-name> <password>root123</password> <subprotocol>mysql</subprotocol> <database>test</database> <driver>com.mysql.jdbc.Driver</driver> </target> </targets> <enable-transaction>true</enable-transaction> <statement> <query>select ID, NAME, DEPT, EMAIL From employee Where DEPT = ?</query> <parameter-sets> <parameter-set> <parameter> <data-type>VARCHAR</data-type> <value>BMC</value> </parameter> </parameter-set> </parameter-sets> </statement> </sql-adapter-request>

Figure 327 on page 415 shows an XML sample for the SQL actor adapter request with a stored procedure. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

414

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter requestParameterized Statement

Figure 327 XML sample of the SQL actor adapter request with a stored procedure
<sqlAdapterRequest> <targets> <target name="mysql"></target> <target name="oracle"></target> <target name="oracle1"> <host>localhost</host> <port>3306</port> <user-name>root</user-name> <password>root123</password> <subprotocol>mysql</subprotocol> <database>test</database> <driver>com.mysql.jdbc.Driver</driver> </target> </targets> <procedure> <name>updateTest</name> <argument-sets> <argument-set> <argument> <in-out>IN</in-out> <data-type>VARCHAR</data-type> <value>sample value</value> </argument> <argument> <in-out>IN</in-out> <data-type>VARCHAR</data-type> <value>New sample value</value> </argument> </argument-set> <argument-set> <argument> <in-out>IN</in-out> <data-type>VARCHAR</data-type> <value>SomeAdapterName</value> </argument> <argument> <in-out>IN</in-out> <data-type>VARCHAR</data-type> <value>SqlAdapterName</value> </argument> </argument-set> </argument-sets> </procedure> </sqlAdapterRequest>

NOTE
You must enter Procedure in Action box if you use the Call Adapter activity to call a stored procedure in BMC Atrium Orchestrator Development Studio.

Chapter 4 Additional base adapters

415

SQL actor adapter responseParameterized Statement

SQL actor adapter responseParameterized Statement

Table 145 describes the adapter response elements for the SQL actor adapter with parameterized statements. Table 145 SQLparameterized statement actor adapter response elements (part 1 of 2)
Element <database> <status> Description Specifies the database name Indicates the status of the request Valid values: success, error <error> Contains the error message if a statement level error occurs When the value of the <status> element is success, this element is absent. <statementresponses> <statementresponse> <statementmetadata> <response-setcount> Contains the <statement-response> elements Contains the <statement-metadata> and the <response-sets> elements Contains the statement level summary information Indicates the number of response sets returned by the query This must correspond directly to the number of parameter sets provided in the request. <status> Indicates the status of the request Valid values: success, error <error> Contains the error message if a statement level error occurs When the value of the <status> element is success, this element is absent. <response-sets> <response-set> Contains the <response-set> elements Contains the information returned by the query The index attribute indicates the sequence of the parameter set as provided in the adapter request. <response-setmetadata> <status> Contains the response level summary information Indicates the status of the request Valid values: success, error <error> Contains the error message if a response level error occurs When the value of the <status> element is success, this element is absent. <target-metadata> Contains target level summary information <database-vendor> Specifies the database vendor name

416

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter responseParameterized Statement

Table 145 SQLparameterized statement actor adapter response elements (part 2 of 2)

Element <result-sets> <result-set> <row> <column> <metadata> <query-executed> <row-count> <column-count> <status> Description Contains the <result-set> element Contains the query results for a specific parameter set Contains the values returned for one row of the query Specifies the column name and the value returned in the response Contains the result level summary information Indicates the query that is executed to return the results Specifies the number of rows returned for the result Specifies the number of columns returned for each row Indicates the status of the request Valid values: success, error <error> Contains the error message if a result level error occurs When the value of the <status> element is success, this element is absent.

Figure 328 illustrates an XML sample of the adapter response for the SQL actor adapter with the parameterized statement. Figure 328 XML sample of the SQL actor adapter response with a parameterized statement (legacy) (part 1 of 2)
<sql-adapter-response> <statement-responses> <statement-response> <statement-metadata> <status>Success</status> <response-set-count>1</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index = "1"> <response-set-metadata> <status>success</status> </response-set-metadata> <result-sets>

Chapter 4 Additional base adapters

417

SQL actor adapter responseParameterized Statement

Figure 328 XML sample of the SQL actor adapter response with a parameterized statement (legacy) (part 2 of 2)
<result-set> <row> <column name = "ID" label = "ID">1001</column> <column name = "NAME" label = "NAME">Test User 1</column> <column name = "DEPT" label = "DEPT">BMC</column> <column name = "EMAIL" label = "EMAIL">testusr1.com</column> </row> <row> <column name = "ID" label = "ID">1004</column> <column name = "NAME" label = "NAME">Test User 2</column> <column name = "DEPT" label = "DEPT">BMC</column> <column name = "EMAIL" label = "EMAIL">testusr2.com</column> </row> <metadata> <query-executed>select ID, NAME, DEPT, EMAIL From employee Where DEPT = ?</query-executed> <execution-milliseconds>10</executionmilliseconds> <row-count>2</row-count> <column-count>4</column-count> <status>success</status> </metadata> </result-set> </result-sets> </response-set> </response-sets> </statement-response> </statement-responses> </sql-adapter-response>

Figure 329 illustrates a dynamic XML sample of the adapter response for the SQL actor adapter. Figure 329 XML sample of an SQLparameterized statement actor adapter response (dynamic) (part 1 of 2)
<sql-adapter-response> <metadata> <status>success</status> </metadata> <targets-output> <target-output name="ARSA"> <target-metadata> <database>testdb</database> <database-vendor>Oracle</database-vendor> <status>success</status> </target-metadata>

418

BMC Atrium Orchestrator Base Adapters User Guide

SQL actor adapter responseParameterized Statement

Figure 329 XML sample of an SQLparameterized statement actor adapter response (dynamic) (part 2 of 2)
<statement-responses> <statement-response> <statement-metadata> <response-set-count>0</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index="1"> <response-set-metadata> <status>success</status> </response-set-metadata> <result-sets> <result-set> <row> <column name="PERSON_ID" label="PERSON_ID">800</column> <column name="LAST_NAME" label="LAST_NAME">DUGAR</column> <column name="FIRST_NAME" label="FIRST_NAME">RITESH</column> <column name="ADDRESS" label="ADDRESS">NEW DELHI</column> <column name="CITY" label="CITY">DELHI</column> </row> <metadata> <query-executed>select * from person where LAST_NAME like 'D%' </query-executed> <execution-milliseconds>3</execution-milliseconds> <row-count>1</row-count> <column-count>5</column-count> <status>success</status> </metadata> </result-set> </result-sets> </response-set> </response-sets> </statement-response> <statement-response> <statement-metadata> <response-set-count>0</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index="1"> <response-set-metadata> <status>success</status> </response-set-metadata> <result-sets> <result-set> <row> <column name="PERSON_ID" label="PERSON_ID">900</column> <column name="LAST_NAME" label="LAST_NAME">Malhotra</column> <column name="FIRST_NAME" label="FIRST_NAME">Vikas</column> <column name="ADDRESS" label="ADDRESS">noida</column> <column name="CITY" label="CITY">UP</column> </row> <metadata> <query-executed>select * from person where LAST_NAME like 'M%' </query-executed> <execution-milliseconds>2</execution-milliseconds> <row-count>1</row-count> <column-count>5</column-count> <status>success</status> </metadata> </result-set> </result-sets> </response-set> </response-sets> </statement-response> </statement-responses> </target-output> </targets-output> </sql-adapter-response>

Chapter 4 Additional base adapters

419

Oracle XMLType data type support

Oracle XMLType data type support

The SQL actor adapter supports Oracle XMLType data type for standard SQL statements, parameterized statements, and stored procedures if the value of the <data-type> element is XMLTYPE, an Oracle XMLType data type in the adapter configuration or adapter request. Figure 330 shows an XML sample of the SQL actor adapter request that supports Oracle XMLType data type. Figure 330 XML sample of the SQL actor adapter request supporting Oracle XMLType data type
<sql-adapter-request> <statements> <statement> <query><![CDATA[INSERT INTO whNo="100"> <Building>Rented</Building> </statement> <statement> <query><![CDATA[INSERT INTO whNo="100"> <Building>Rented</Building> </statement> </statements> </sql-adapter-request>

warehouses VALUES ( 500, XMLType( '<Warehouse </Warehouse>'), 'Tower Records', 1003)]]></query> warehouses VALUES ( 600, XMLType( '<Warehouse </Warehouse>'), 'Tower Records', 1003)]]></query>

Figure 331 on page 421 shows an XML sample of the SQL actor adapter response that supports Oracle XMLType data type.

420

BMC Atrium Orchestrator Base Adapters User Guide

Oracle XMLType data type support

Figure 331 XML sample of the SQL actor adapter response supporting Oracle XMLType data type (part 1 of 2)
<sql-adapter-response> <statement-responses> <statement-response> <statement-metadata> <response-set-count>0</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index = "1"> <response-set-metadata> <update-count>1</update-count> <status>success</status> </response-set-metadata> </response-set> </response-sets> </statement-response> <statement-response> <statement-metadata> <response-set-count>0</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index = "1"> <response-set-metadata> <update-count>1</update-count> <status>success</status> </response-set-metadata> </response-set> </response-sets> </statement-response> <statement-response> <statement-metadata> <response-set-count>0</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index = "1"> <response-set-metadata> <update-count>1</update-count> <status>success</status> </response-set-metadata> </response-set> </response-sets> </statement-response> </statement-responses> </sql-adapter-response> <sql-adapter-request> <statements> <statement> <query><![CDATA[INSERT INTO warehouses VALUES (?,?,?,?)]]></query> <parameter-sets> <parameter-set> <parameter> <data-type>NUMBER</data-type> <value>4785</value> </parameter>

Chapter 4 Additional base adapters

421

Oracle XMLType data type support

Figure 331 XML sample of the SQL actor adapter response supporting Oracle XMLType data type (part 2 of 2)
<parameter> <data-type>XMLTYPE</data-type> <value><![CDATA[<Warehouse whNo="189"><Building>TestXMLparasupport</Building></Warehouse>]]></value> </parameter> <parameter> <data-type>VARCHAR</data-type> <value>OneEightNine</value> </parameter> <parameter> <data-type>NUMBER</data-type> <value>4895</value> </parameter> </parameter-set> </parameter-sets> </statement> </statements> </sql-adapter-request> <sql-adapter-response> <statement-responses> <statement-response> <statement-metadata> <response-set-count>1</response-set-count> <status>success</status> </statement-metadata> <response-sets> <response-set index = "1"> <response-set-metadata> <update-count>1</update-count> <status>success</status> </response-set-metadata> </response-set> </response-sets> </statement-response> </statement-responses> </sql-adapter-response>

Ensure that you perform the following tasks:

1 Copy the required third party (client-specific) .JAR files to the

%AO_HOME%/lib/add-ons directory.

2 Locate the .JAR files from the appropriate location where the Oracle database is
installed. Table 146 Third party (client-specific) JAR files to be copied
Jar file name xdb.jar classes12.zip xmlparserv2.jar ojdbc14.jar Oracle database installation location from which to pick the JAR file %ORACLE_HOME%\RDBMS\jlib %ORACLE_HOME%\jdbc\lib %ORACLE_HOME%\LIB %ORACLE_HOME%\jdbc\lib

422

BMC Atrium Orchestrator Base Adapters User Guide

Installing JDBC OCI Instant Client Libraries

NOTE
Oracle thin client supports only queries that do not perform the XQuery operation on XMLType data type. For example:
s

INSERT INTO warehouses VALUES (100, XMLType('<Warehouse whNo="100"><Building>Owned</Building></Warehouse>'), 'Tower Records', 1003);

UPDATE warehouses SET warehouse_spec = XMLType('<Warehouse whono="222"><Building>Leased1</Building></Warehouse>');

You need Oracle Call Interface (OCI) client libraries if you use XQuery strings in the SQL query. In other words, you need to use an OCI (thick) client if the SQL query has an XQuery operation on XMLType data type, such as extract(). For example: DELETE FROM warehouses e WHERE e.warehouse_spec.extract ('//Building/text()').getStringVal()= 'Lease')

Installing JDBC OCI Instant Client Libraries

You can install the Instant Client libraries by choosing the Instant Client option from the Oracle Universal Installer. Also, you can download the Instant Client libraries from the Oracle Technology Network website.

To install JDBC OCI Instant Client libraries 1 Download and install the Instant Client shared libraries and Oracle JDBC class
libraries to a directory, for example, instantclient.

2 Set the library path environment variable to the directory specified in step 1.
For example: On UNIX, set LD_LIBRARY_PATH to instantclient. On Windows, set PATH to locate the instantclient directory.

3 Add the full path names of the JDBC class libraries to the CLASSPATH
environment variable.

Chapter 4 Additional base adapters

423

SQL monitor adapter

NOTE
Library names of Oracle JDBC 10.2 release are used in Table 147. The names may vary depending on the OCI client version that has been installed. The files must be in CLASSPATH and %AO_HOME%/lib/add-ons directory.

Table 147 Oracle client-side files required to deploy a JDBC OCI application
Linux and UNIX libclnstsh.so.10.1 libociei.so libnnz10.so libocijdbc10.so Description for Linux and UNIX Client Code Library OCI Instant Client Data Shared Library Security Library OCI Instant Client JDBC Library Windows oci.dll oraociei10.dll orannzsbb10.dll oraocijdbc10.dll Description for Windows Forwarding functions to which applications link Data and code Security Library OCI Instant Client JDBC Library

SQL monitor adapter

The SQL monitor adapter is used to query an SQL database at a specified interval. You can create rules that execute specific processes based on the results of the query. You can configure multiple SQL monitor adapters within Grid Manager, each with a unique configuration node and adapter name. A single SQL monitor adapter can configure multiple target computers. Each target has multiple events or queries associated with it. The adapter checks if multiple targets are configured while initializing the adapter.
s

If all the targets are up, the adapter is in a Running state. If one of the targets is unavailable, the adapter is in a Fault state. The adapter sends events to recover the failed target. The adapter pings the target every three minutes and once the failed target is up, the adapter is in Running state.

This section describes the following configuration and event formats of the SQL monitor adapter:

SQL monitor adapter configuration

SQL monitor adapter event

424

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter configuration

SQL monitor adapter configuration

Adapter type: ro-adapter-sql-monitor[version] You can define the URL for an SQL query in the following ways:
s

Define the target, port, subprotocol, database, and any parameter as elements in the configuration, allowing the process to form the URL.

Figure 332 is an excerpt from the SQL actor adapter configuration that depicts method 1 of defining the URL. You need supporting elements to form the complete configuration. Figure 332 XML sample of method 1 for defining a URL
<host>host1</host> <port>port1</port> <subprotocol>oracle:thin</subprotocol> <database>database1</database>

Define the complete URL, including parameters, in a single element in the configuration.

Figure 333 is an excerpt from the SQL actor adapter configuration that depicts method 2 to define the URL. You need supporting elements to form the complete configuration. Figure 333 XML sample of method 2 for defining a URL
<url>jdbc:oracle:thin:@target1:port1:database1?param1=abc&param2=xyz</url>

Table 148 describes the adapter configuration elements for the SQL monitor adapter.

NOTE
The SQL monitor adapter does not support form based adapter configuration at all. You would have to configure this adapter using the XML view. To configure the adapter, see Configuring the adapter on page 14.

Table 148 SQL monitor adapter configuration node elements (part 1 of 4)

Element <targets> <target> Description Contains the <target> element Contains the SQL server, database, and connection information. This element has a name attribute that provides a target name. If the target name has a default attribute with the value set to true, the target is a global target, else the target is a local target. Required Yes No

Chapter 4 Additional base adapters

425

SQL monitor adapter configuration

Table 148 SQL monitor adapter configuration node elements (part 2 of 4)

Element <url> Description Specifies the complete connection URL for the target database If you do specify this element, you must specify <host>, <port>, <subprotocol>, and <database> elements (as needed) so that the process can create the URL. <host> Specifies the host name or the IP address of the database server This element is required in the absence of the <url> element. <port> Specifies the port on which the database server listens The requirements for the JDBC driver specified in the <driver> element determine whether the <port> element is required. This element is not used if you specify the <url> element. <user-name> Specifies the user name to be used for database authentication The database requirements in the user's environment determine whether the <user-name> element is required. <password> Specifies the password that corresponds to the <user-name> provided The database requirements in the user's environment determine whether the <password> element is required. <subprotocol> Specifies the driver specified subprotocol, used to build the connection URL The adapter prepends jdbc: to the value provided. This element is required in the absence of the <url> element.
s s

Required No

Conditional

Conditional

Conditional

Conditional

Conditional

Format: <database type>:<subprotocol> Sample values: sybase:Tds, oracle:thin Conditional

<database>

Specifies the name of the database to which the adapter connects This element is required in the absence of the <url> element.

<driver>

Specifies the fully qualified JDBC driver classname. The sample values are:
s s

Yes

com.sybase.jdbc3.jdbc.SybDriver oracle.jdbc.driver.OracleDriver No

<max-wait>

Specifies the maximum time, in milliseconds, to wait before timing out when establishing a connection to a database Default value: 60,000 milliseconds (1 minute)

<maxconnectionidle-timemillis>

Specifies the maximum time, in milliseconds that a connection can remain No idle before it is closed Default value: 300,000 milliseconds (5 minutes)

426

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter configuration

Table 148 SQL monitor adapter configuration node elements (part 3 of 4)

Element <minconnectionidle-timemillis> <evictoridle-timemillis> Description Required Specifies the minimum time, in milliseconds that a connection can remain No idle before being evaluated for termination Default value: 120,000 milliseconds (2 minutes) Specifies the frequency, in milliseconds, in which a thread used to close idle connections runs Note: Set the value of this element lower than the value of the <maxconnection-idle-time-millis> element. Default value: 60,000 milliseconds (1 minute) <max-activeconnections> Specifies the maximum number of connections allowed at any time in the No connection pool Default value: 10 <initialactive>connections Specifies the minimum number of connections created during adapter startup The poolable API of Apache software does not support this feature. However, the BasicDataSource (non-poolable-version), supports this feature. Default value: 2 <max-idleconnections> <min-idleconnections> <validatequery> Specifies the maximum number of idle connections allowed at any time Default value: 5 Specifies the minimum number of idle connections allowed at any time Default value: 0 Specifies the query statement used to validate the connection This element is required in the presence of the <validateconnections-on-return> or <validate-idle-connections> element. <validateconnectionson-return> Indicates whether a connection is validated when it is returned to the pool No The <validate-query> element must be present to use this feature. Valid values: true, false (default) With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. Conditional No No No No

Chapter 4 Additional base adapters

427

SQL monitor adapter configuration

Table 148 SQL monitor adapter configuration node elements (part 4 of 4)

Element <validateidleconnections> Description Required Indicates whether periodic checks are done on idle connections in the pool No (set of connections) The <validate-query> element must be present to use this feature. Valid values: true, false (default) With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. <eventstatements> <eventstatement> <query> Contains the <event-statement> elements Yes

Contains the details about the query to be performed on the specified host Yes Specifies the query to be executed periodically on the specified database The query results are returned in the adapter response. The SQL query for a Monitor adapter only supports SELECT statements, not INSERT, UPDATE, and DELETE statements. Yes

<pollinterval>

Specifies the frequency, in seconds, in which the specified <host> is queried Default value: 60 seconds

No

<singlemonitorevent> <ktgt-cachefile>

Generates a single event for all the records retrieved by the <query> statement Valid values: true (default), false Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

No

No

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> <krb-service- Specifies the name of the service principal registered with the Sybase principal> database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

428

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter configuration

Figure 334 shows an XML sample of the non-URL SQL monitor adapter configuration. Figure 334 XML sample of the SQL monitor adapter configurationnon-URL
<config> <targets> <target name = "target1" default = "true"> <host>localhost</host> <port>3306</port> <user-name>root</user-name> <password>qbasic</password> <subprotocol>mysql</subprotocol> <database>moviedb</database> <driver>com.mysql.jdbc.Driver</driver> <max-wait>1200</max-wait> <max-connection-idle-time-millis>10000</max-connection-idle-time-millis> <min-connection-idle-time-millis>1000</min-connection-idle-time-millis> <evictor-idle-time-millis>5000</evictor-idle-time-millis> <max-active-connections>20</max-active-connections> <initial-active-connections>2</initial-active-connections> <max-idle-connections>5</max-idle-connections> <min-idle-connections>1</min-idle-connections> <validate-connections-on-return>true</validate-connections-on-return> <validate-idle-connections>true</validate-idle-connections> <validate-query>select sysdate from dual</validate-query> </target> </targets> <event-statements> <event-statement> <query>select * from movie</query> <poll-interval>2</poll-interval> (In Seconds) <single-monitor-event>true</single-monitor-event> </event-statement> <event-statement> <query>select * from movietype</query> <poll-interval>4</poll-interval> <single-monitor-event>true</single-monitor-event> </event-statement> </event-statements> </config>

Chapter 4 Additional base adapters

429

SQL monitor adapter configuration

Figure 335 shows an XML sample of the non-URL SQL monitor adapter configuration supporting stored procedures. Figure 335 XML sample of the SQL monitor adapter configurationnon-URL supporting a stored procedure
<config> <targets> <target name="oracle" default = "true"> <user-name>u1</user-name> <password>p1</password> <driver>oracle.jdbc.driver.OracleDriver</driver> <host>localhost</host> <port>1521</port> <subprotocol>oracle:thin</subprotocol> <database>D1</database> </target> </targets> <event-statements> <event-statement> <procedure> <name>customer_pkg.getCustomerCount</name> <argument-set> <argument> <index>1</index> <in-out>IN</in-out> <data-type>VARCHAR</data-type> <value>c1</value> </argument> <argument> <index>2</index> <in-out>IN</in-out> <data-type>NUMBER</data-type> </argument> </argument-set> </procedure> <poll-interval>4</poll-interval> <single-monitor-event>true</single-monitor-event> </event-statement> </event-statements> </config>

NOTE
When the value of the <in-out> parameter is IN, the <index> parameter does not exist.

430

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter configuration

Figure 336 shows an XML sample of the SQL monitor adapter configuration with a function returning an integer. Figure 336 XML sample of the SQL monitor adapter configuration with a function returning an integer
<config> <targets> <target name="oracle" default="true"> <host>10.254.1.78</host> <port>1521</port> <user-name>bmcadmin</user-name> <password>abc123</password> <subprotocol>oracle:thin</subprotocol> <database>testdb</database> <driver>oracle.jdbc.driver.OracleDriver</driver> </target> </targets> <event-statements> <event-statement> <procedure> <name>Testing</name> <return-data-type>INTEGER</return-data-type> <argument-set> <argument> <index>1</index> <in-out>IN</in-out> <data-type>NUMBER</data-type> <value>100</value> </argument> </argument-set> </procedure> <poll-interval>60</poll-interval> <single-monitor-event>true</single-monitor-event> </event-statement> </event-statements> </config>

Chapter 4 Additional base adapters

431

SQL monitor adapter configuration

Figure 337 shows an XML sample of the URL SQL monitor adapter configuration. Figure 337 XML sample of the SQL monitor adapter configurationURL
<config> <targets> <target name = "mysql_bpm" default = "true"> <url>jdbc:mysql://localhost:3306/test</url> <user-name>root</user-name> <password>root123</password> <driver>com.mysql.jdbc.Driver</driver> <max-wait>1200</max-wait> </target> <target name = "mysql_cmdb" default = "true"> <url>jdbc:mysql://localhost:3306/firstuser</url> <user-name>firstuser</user-name> <password>firstuser</password> <driver>com.mysql.jdbc.Driver</driver> <max-wait>1200</max-wait> </target> </targets> <event-statements> <event-statement> <query>select * from test</query> <poll-interval>15</poll-interval> <single-monitor-event>true</single-monitor-event> <targets> <target>mysql_cmdb</target> </targets> </event-statement> <event-statement> <query>select * from test</query> <poll-interval>20</poll-interval> <single-monitor-event>true</single-monitor-event> </event-statement> </event-statements> </config>

Figure 338 shows an XML sample of the SQL monitor adapter configuration with Sybase Kerberos Authentication. Figure 338 XML sample of the SQL monitor adapter configuration with Sybase Kerberos Authentication
<config> <targets> <target name="SybaseDB1" default="true"> <url>jdbc:sybase:Tds:10.128.248.105:5000/MASTER</url> <user-name>sybuser1</user-name> <driver>com.sybase.jdbc3.jdbc.SybDriver</driver> <password /> <database>master</database> <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cache-file> <krb-service-principal>REALOPSLINUX1@SYNAPSE.COM</krb-service-principal> </target> </targets> <event-statements> <event-statement> <query>select * from spt_monitor</query> <poll-interval>15</poll-interval> <single-monitor-event>true</single-monitor-event> </event-statement> </event-statements> </config>

432

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter event

SQL monitor adapter event

The elements contained in the SQL Monitor adapter event are different depending on the value for the <single-monitor-event> element defined in the adapter configuration. Table 149 describes the elements of the SQL monitor adapter when the <singlemonitor-event> element is true. Table 149 SQL monitor with single monitor event true adapter event elements
Element <row <column> <metadata> <target-name> <query-executed> <response-row-count> <status> Description Contains the values returned for one row of the query Specifies the column name and the value returned in the response Contains the summary information for the request Specifies the host on which the query is executed Specifies the syntax of the query defined in the adapter request Specifies the number of rows returned in the response Indicates the status of the request execution Valid values: success, error <error> Contains the error message if an interruption occurs during the execution of a request When the value of the <status> element is success, this element is absent.

<response-column-count> Specifies the number of columns returned for each row

Chapter 4 Additional base adapters

433

SQL monitor adapter event

Figure 339 shows an XML sample of the adapter event for the SQL monitor adapter when the <single-monitor-event> element is true. Figure 339 XML sample of the SQL monitor adapter event when the <single-monitor-event> element is true
<sql-monitor-event> <row> <column name="movie_id">1</column> <column name="movie_name">Bruce Almighty</column> <column name="movie_type">5</column> <column name="movie_year">2003</column> <column name="movie_leadactor">1</column> <column name="movie_director">2</column> <column name="movie_running_time">102</column> <column name="movie_cost">10</column> </row> <row> <column name="movie_id">2</column> <column name="movie_name">Office Space</column> <column name="movie_type">5</column> <column name="movie_year">1999</column> <column name="movie_leadactor">5</column> <column name="movie_director">6</column> <column name="movie_running_time">90</column> <column name="movie_cost">3</column> </row> <metadata> <query-executed>select * from movie</query-executed> <target-name>target1</target-name> <response-row-count>2</response-row-ccount> <response-column-count>8</response-column-count> <status>success</status> </metadata> </sql-monitor-event>

Figure 340 shows an XML sample of the adapter event for the SQL monitor adapter supporting a stored procedure. Figure 340 XML sample of the SQL monitor adapter event supporting a stored procedure
<sql-monitor-event> <response-sets> <response-set index="1"> <out-params> <column name="2">2</column> </out-params> <response-set-metadata> <out-param-count>1</out-param-count> <has-result-set>false</has-result-set> <status>success</status> </response-set-metadata> </response-set> </response-sets> <procedure-metadata> <response-set-count>1</response-set-count> <query-executed>{call customer_pkg.getCustomerCount(?, ?) }</query-executed> <status>success</status> </procedure-metadata> </sql-monitor-event>

434

BMC Atrium Orchestrator Base Adapters User Guide

SQL monitor adapter event

NOTE
You can also invoke a function or a stored procedure to return a cursor.

Figure 341 shows an XML sample of the of the SQL monitor adapter when the <single-monitor-event> element is false. Figure 341 XML sample of the SQL monitor adapter when the <single-monitor-event> element is falsesingle event
<sql-monitor-event> <row> <column name="movie_id">1</column> <column name="movie_name">Bruce Almighty</column> <column name="movie_type">5</column> <column name="movie_year">2003</column> <column name="movie_leadactor">1</column> <column name="movie_director">2</column> <column name="movie_running_time">102</column> <column name="movie_cost">10</column> </row> <metadata> <target-name>target1</target-name> <query-executed>select * from movie</query-executed> <row-number>1</row-number> <response-row-count>2</response-row-count> <response-column-count>8</response-column-count> <status>success</status> </metadata> </sql-monitor-event>

Table 150 describes the elements of the SQL monitor adapter when the <singlemonitor-event> element is false.

Table 150 SQL single monitor adapter event false- event two elements (part 1 of 2)
Element <row> <column> <metadata> <target-name> <query-executed> <executionmilliseconds> <row-number> Description The values returned for one row of the query The column name and value returned in the response The summary information for the request The host on which the query is executed The syntax of the query defined in the adapter request The duration of the request execution, in milliseconds The reference number for the row information contained in this event Each event generated contains information for a single row. <response-row-count> The number of rows returned in the response <response-columncount> The number of columns returned for each row

Chapter 4 Additional base adapters

435

SQL adapter FAQs

Table 150 SQL single monitor adapter event false- event two elements (part 2 of 2)
Element <status> Description Indicates the status of the request execution Valid values: success, error <error> Contains the error message if an interruption occurs during the execution of a request When the value of the <status> element is success, this element is absent.

Figure 334 shows an XML sample of the adapter event for the SQL monitor adapter when the <single-monitor-event> element is false. Figure 342 XML sample of the SQL monitor adapter when the <single-monitor-event> element is falsetwo events
<sql-monitor-event> <row> <column name="movie_id">3</column> <column name="movie_name">Grand Canyon</column> <column name="movie_type">2</column> <column name="movie_year">1991</column> <column name="movie_leadactor">4</column> <column name="movie_director">3</column> <column name="movie_running_time">134</column> <column name="movie_cost">15</column> </row> <metadata> <target-name>target1</target-name> <query-executed>select * from movie</query-executed> <row-number>2</row-number> <response-row-count>2</response-row-count> <response-column-count>8</response-column-count> <status>success</status> </metadata> </sql-monitor-event>

SQL adapter FAQs

Does the SQL adapter automatically close down its connection?

Explanation: The SQL monitor adapter does not close a connection because it has to keep monitoring the target database.
Does BMC Atrium Orchestrator use the SQL adapter to update the metrics table?

Explanation: No, the SQL adapter does not need to be installed or active to communicate with the metrics database.

436

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter

Does BMC Atrium Orchestrator connect to the metrics table only when there's an update to be made?

Explanation: Yes, BMC Atrium Orchestrator connects to the metrics table depending on the frequency set for metric uploads. Once set, the peer connects to the database to write data even if there are no changes in memory. For example, you could set the frequency to every 30 seconds up to multiple hours.
How can you log connections to Oracle using the adapter and connections made to the metrics table?

Explanation: You can track connections via the adapter by turning the adapter to debug logging. You can track connections to the metrics database by turning the metrics to debug logging. Logging metrics is one of the many components of a peer and can be logged in Grid Manager. Logging depends on exactly what and how you need to track.
Are there any housekeeping tasks that you need to do to clean up dead connections from BMC Atrium Orchestrator?

Explanation: Connections need to be cleaned if something goes wrong, like connectivity issues or a system failure. Normally, no manual cleanup is required.

Web Services adapter

The Web Services adapter is used to make Remote Procedure Call (RPC) requests using Simple Object Access Protocol (SOAP). This adapter does not require a configuration node. However, you must configure the adapter in Grid Manager. The Web Services adapter can use a standard HTTP proxy server for establishing outbound HTTP connections. The Web Services adapter supports only basic authentication for the proxy server that is used. This section describes the configuration, request format, and response format of the Web Services adapter.

Web Services adapter configuration Web Services adapter responsemethod one Web Services adapter requestJAX-WS Approach Web Services adapter request for Make SOAP RequestMessage mode

Web Services adapter request Web Services adapter requestmethod two Web Services adapter request for Make SOAP RequestPayload mode Web Services adapter response for Make SOAP RequestMessage mode

Chapter 4 Additional base adapters

437

Web Services adapter configuration

Web Services adapter response for a request with Poll Asynchronous Response Web Services adapter responsemethod two Web Services adapter request for Poll Asynchronous Response

Web Services adapter requestmethod one Web Services adapter response for Make SOAP RequestPayload mode

Web Services adapter configuration

Adapter type: ro-adapter-ws[version] Default adapter name: SOAPAdapter If you use a proxy server for Internet connectivity, use the proxy settings shown in the <config> section in Figure 345. To configure the Web Services adapter, see Configuring the adapter on page 14. Table 151 describes the adapter configuration elements for the Web Services adapter that you can specify by 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. Table 151 Web Services adapter configuration elements (part 1 of 5)
UI label Clear Asynchronous Cache Delay Timestamp Element Description Required No <clearPeriodically clears the cache that stores responses to asynchronous asynchronous requests -cache> Valid values: true (default), false <delay> <timestamp>

Specifies the delay in minutes taken by the adapter to No clear the cache Builds a Web Services timestamp and inserts it into the SOAP envelope Valid values: true, false (default) No

Time To Live

<time-tolive>

Sets the time difference (in seconds) between the Created and the Expires values in the timestamp Default value: 60 seconds

No

Username Token

<usernametoken>

Builds a Web Services username token and inserts it into the SOAP envelope Valid values: true, false (default)

No

438

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter configuration

Table 151 Web Services adapter configuration elements (part 2 of 5)

UI label User Name Element <user-name> Description Specifies the user name for the username token This element is required if the value of the <username-token> element is true. Password <password> Specifies the password for the username token This element is required if the value of the <username-token> element is true. Password Type <passwordtype> Specifies the type of password supported for username token authentication This element is read-only if the value of the <username-token> element is true. Valid values: plain-text (default), digest Nonce Validation <noncevalidation> Adds a nonce element to the username-token Nonce is a randomly generated, cryptographic token used to prevent replay attacks. Without nonce, when a UsernameToken is passed from one computer to another computer using a non-secure transport, such as HTTP, the token might be intercepted and used in a replay attack. Valid values: true, false (default) Created Validation <createdvalidation> Adds a created element to the username-token To help eliminate replay attacks, <nonce> and <created> elements are generated within the <username-token> element and used to validate the message. The server checks the freshness of the message by verifying that the difference between the <nonce> element creation time, which is specified by the <created> element, and the current time is within a specified time. Valid values: true, false (default) Sign Request <signrequest> Creates a signature according to the Web Services specification X.509 profile and adds it to the security header The Token Reference supported by the adapter is Binary Security Token. Valid values: true, false (default) No No No No Conditional Required Conditional

Chapter 4 Additional base adapters

439

Web Services adapter configuration

Table 151 Web Services adapter configuration elements (part 3 of 5)

UI label None Element <signatureproperties> Description Required Contains the elements used to specify the information No about the X.509 certificate (public key) and the private key that are used for XML digital signature Valid values for the mode attribute: key-store (default), key-files, and key-data None <signusernametoken> <signtimestamp> Signs the Web Services <username-token> element No in the Security header Valid values: true, false (default) None Signs the Web Services <timestamp> element in the No Security header Valid values: true, false (default) None <privatekey-file> Specifies the file containing the Private Key used to sign the SOAP message using the signing algorithm The adapter supports the following formats:
s s

Conditional

Base64-encoded unencrypted Privacy Enhanced Mail (PEM) Definite Encoding Rules (DER)

This element is required if the value of the mode attribute of the <signature-properties> element is key-files. None <certificate Specifies the file containing the X.509 Certificate -file (Public Key) The adapter supports the following formats:
s s

Conditional

Base64-encoded unencrypted Privacy Enhanced Mail (PEM) Definite Encoding Rules (DER)

This element is required if the value of the mode attribute of the <signature-properties> element is key-files. None <privatekey-data> Specifies the Private Key in unencrypted Base64encoded PEM format This element is required if the value of the mode attribute of the <signature-properties> element is key-data. Conditional

440

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter configuration

Table 151 Web Services adapter configuration elements (part 4 of 5)

UI label None Element Description Required Conditional <certificate Specifies the X.509 Certificate (Public Key) in -data> unencrypted Base64-encoded PEM format This element is required if the value of the mode attribute of the <signature-properties> element is key-data. None <keystorefile> Configures the adapter to use the Java Keystore (JKS) Conditional specified by the keystore-filename The adapter must contain the absolute path of the keystore file This element is required if the value of the mode attribute of the <signature-properties> element is key-store. None <keystorepassword> Specifies the password of the keystore This element is required if the value of the mode attribute of the <signature-properties> element is key-store. None <alias> Specifies the user's alias name in the keystore that identifies the Private Key to sign the document This element is required if the value of the mode attribute of the <signature-properties> element is key-store. None None None <password> <proxysettings> <host> Specifies the user's password to get the Private Signing Key from the keystore Contains the elements that define the HTTP proxy settings Specifies the host name or the IP address of the host for the Web service request This element is required if the <proxy-settings> element is used. None <port> Specifies the destination port for the Web service request This element is required if the <proxy-settings> element is used. Conditional No No Conditional Conditional Conditional

Chapter 4 Additional base adapters

441

Web Services adapter configuration

Table 151 Web Services adapter configuration elements (part 5 of 5)

UI label None Element <user-name> Description Required Specifies the name of the user, who requests the proxy Conditional service This element is required if the <proxy-settings> element is used and authentication is enabled and necessary on the proxy server. None <password> Specifies the password for the user on the specified host This element is required if the <proxy-settings> element is used and authentication is enabled and necessary on the proxy server. Conditional

NOTE
The proxy settings elements in the adapter configuration are applicable only to method two and JAX-WS approach.

While the adapter does not require a configuration node, an XML tag, <config/> is required for the Properties field in Grid Manager adapter configuration. Figure 343 shows an XML template of the adapter configuration for the Web Services adapter. The following configuration clears the cache after a delay of 120 minutes. Figure 343 XML template of the Web Services adapter configuration
<config> <clear-asynchronous-cache></clear-asynchronous-cache> <delay></delay> <timestamp></timestamp> <time-to-live></time-to-live> <username-token></username-token> <user-name></user-name> <password></password> <password-type></password-type> <nonce-validation></nonce-validation> <created-validation></created-validation> <sign-request></sign-request> <signature-properties mode="key-files"> <sign-username-token></sign-username-token> <sign-timestamp></sign-timestamp> <private-key-file></private-key-file> <certificate-file></certificate-file> </signature-properties> <signature-properties mode="key-data"> <private-key-data></private-key-data> <certificate-data></certificate-data> </signature-properties> <signature-properties mode="keystore"> <keystore-file></keystore-file> <keystore-password></keystore-password> <alias></alias> <password></password> </signature-properties> </config>

442

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter configuration

The configuration shown in Figure 344 does not clear the cache. Figure 344 XML sample of the Web Services adapter configuration that does not clear the cache
<config> <clear-asynchronous-cache>false<clear-asynchronous-cache> <delay>120</delay> </config>

Figure 345 shows an XML sample for the Web Services adapter configuration with proxy settings. Figure 345 XML sample for the Web Services adapter configuration with proxy settings
<config> <proxy-settings> <host>10.10.255.255</host> <port>8070</port> <user-name>testuser</user-name> <password>testpassword</password> </proxy-settings> </config>

Figure 346 and Figure 347 show the sample adapter configurations for Web Services that require an XML digital signature and a signed username token in the Security header of the SOAP envelope. For the key-files or the key-data mode, you must provide the X.509 Certificate (Public Key) and the Private Key files or the Private Key data in unencrypted Base64-encoded Privacy Enhanced Mail (PEM) format. Figure 346 XML sample of the Web Services adapter configuration for key-files mode
<config> <timestamp>true</timestamp> <time-to-live>120</time-to-live> <sign-request>true</sign-request> <signature-properties mode="key-files"> <sign-timestamp>true</sign-timestamp> <private-key-file>C:\Security\pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-keyfile> <certificate-file>C:\Security\cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificatefile> </signature-properties> </config>

Chapter 4 Additional base adapters

443

Web Services adapter request

Figure 347 XML sample of the Web Services adapter configuration for key-data mode
<config> <timestamp>true</timestamp> <time-to-live>120</time-to-live> <sign-request>true</sign-request> <signature-properties mode="key-data"> <sign-timestamp>true</sign-timestamp> <private-key-data>-----BEGIN PRIVATE KEY----MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKomKro6VbW4PeQtUhNzZpSH26vb....IoKFbuJhl n+tlJdmN16mzl1QnyDi469i2C/yXQEvNkjiDQGHrMlhA+0eik8+JuL/TEwgrcOYKP5B I0XNL71L -----END PRIVATE KEY-----</private-key-data> <certificate-data>-----BEGIN CERTIFICATE----MIICdzCCAeCgAwIBAgIFXseN1xYwDQYJKoZIhvcNAQEFBQAwUzELMAkGA1UEBhMC....m/0iDplDR7XkyTxAx0AWo 0RF4mstOszPGbpHBKFri2qxyXM0NmIPX2dJqhKICXP4 8HATrUjWl+peSog= -----END CERTIFICATE-----</certificate-data> </signature-properties> </config>

Figure 348 shows the sample adapter configuration for Web Services that require an XML digital signature and signed username token in the Security header of the SOAP envelope. For the key-store mode, you must provide the keystore (JKS type) containing the X.509 Certificate (Public Key) and the Private Key. Figure 348 XML sample of the Web Services adapter configuration for key-store mode
<config> <username-token>true</username-token> <user-name>Demo</user-name> <password> </password> <password-type>plain-text</password-type> <nonce-validation>true</nonce-validation> <created-validation>true</created-validation> <sign-request>true</sign-request> <signature-properties mode="keystore"> <sign-username-token>true</sign-username-token> <keystore-file>C:\Security\bmcatriumwsclient_7.5.00.001.jks</keystore-file> <keystore-password>atrium</keystore-password> <alias>bmcatriumwsclient</alias> <password>atrium</password> </signature-properties> </config>

Web Services adapter request

The Web Services adapter does not use an action. You must leave the adapters Action field blank when configuring the activity properties for a Call adapter activity in BMC Atrium Orchestrator Development Studio. You can define an adapter request using the following methods:
s

The first method enables you to specify the entire SOAP envelope, thereby enabling complete control to define headers and namespaces. This method supports HTTPS Client Authentication.

444

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter request

The second method relies on the adapter to implement SOAP and requires you to specify only the header and body payloads. The third method uses Java API for XML Web Services (JAX-WS) used by Dispatch API for dynamic invocation of service end point operations, by sending data in payload or message mode. In Make SOAP Request Payload mode, the client provides the contents of the <soap:Body> element and JAX-WS includes the input payload in the <soap:Envelope> element. In Make SOAP Request Message mode, the client provides the entire SOAP envelope. This method supports HTTPS Client Authentication. Poll Asynchronous mode is used when a service operation is invoked asynchronously. The results of the operation are obtained by polling the response.

A connection is named in the request, and subsequent requests can specify this named connection to be reused for a request. The connection remains available until the endpoint of the process, or until the connection is terminated with a <terminateon-exit> element. At that point, the connection and any session cookies are flushed from the cache. A named connection is defined in an adapter request using a <connection> node containing two child elements, <name> and <terminate-on-exit>. The <name> element is required. The <terminate-on-exit> element is optional and defaults to false, if not defined, maintaining the connection and session cookies. The named connection is an optional function. In the absence of a <connection> node, session cookies do not persist beyond the initial request.

SSL Authentication
Secure Sockets Layer (SSL) protocol uses certificates for authentication. Certificates are digitally signed documents, which bind the public key to the identity of the private key owner. Authentication occurs at connection time, and is independent of the application or the application protocol. Authentication involves making sure that servers with which you communicate are who they claim to be. With SSL, authentication is performed by an exchange of certificates, which are blocks of data in a format described in ITU-T standard X.509. The X.509 certificates are issued, and digitally signed by an external authority known as a certificate authority (CA). Certificates are used to authenticate clients to servers, and servers to clients; the mechanism used is essentially the same in both the cases. However, the server certificate is mandatory, that is, the server must send its certificate to the client. However, the client certificate is optional; some clients might not support client certificates; others might not have certificates installed. Servers can decide whether client authentication is required for a connection.
Chapter 4 Additional base adapters 445

Web Services adapter requestmethod one

HTTPS Client Authentication

HTTPS Client Authentication requires the client to possess a Public Key Certificate (PKC). If client authentication is specified, the web server authenticates the client using the client's PKC. HTTPS Client Authentication is a more secure method of authentication than either basic or form-based authentication. HTTPS Client Authentication uses HTTP over SSL (HTTPS), in which the server authenticates the client using the client's PKC. SSL technology provides data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection. PKC is issued by a trusted organization, which is called a certificate authority (CA), and provides identification for the bearer. When using certificate-based mutual authentication, the following actions occur: 1. A client requests access to a protected resource. 2. The web server presents its certificate to the client. 3. The client verifies the server's certificate. 4. If successful, the client sends its certificate to the server. 5. The server verifies the client's credentials. 6. If successful, the server grants access to the protected resource requested by the client.

NTLM Authentication
NTLM authentication is an application protocol used in various Microsoft network protocol implementations and is used throughout the Microsofts systems as an integrated single-on mechanism. NTLM provides a challenge-response authentication mechanism, in which clients are able to prove their identities without sending a password to the server. Web Services adapter supports both NTLMv1 and NTLMv2 authentication.

Web Services adapter requestmethod one

When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags.

446

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter requestmethod one

Table 152 describes the adapter request elements for Web Services adaptermethod one. Table 152 Web Services adapter request elementsmethod one
Element <use-sslcertificate> <installcertificate> <allowunsignedcertificate> <truststorefile> <passphrase> Description Specifies whether to establish a secure connection Default value: false Specifies whether to install certificates Default value: false Specifies whether to allow unsigned certificates from trusted zones Default value: false Specifies the path to the truststore file containing the CAs Default value: Java standard truststore Specifies the password of the truststore file Default value: changeit <keystore-file> <keystorepassphrase> <client-alias> <httpconnectionproperties> <transport> Specifies the path to the keystore containing the client certificate Specifies the password of the keystore file Default value: changeit Specifies the alias name in the keystore that identifies the Public Key No Certificate (PKC) used by the web server to authenticate the client Specifies the HTTP connection properties Yes No No No No No No Required No

Identifies the transport protocol to use for the message Valid value: http-rpc

Yes

<soap-url> <user-name> <password> <ntlmauthentication> <Content-Type> <soap-message> <soap-bodycontent>

Specifies the URL for the remote SOAP service Specifies the user name for HTTP basic authentication Specifies whether to use NTLM authentication Default value: false Specifies the type of HTTP content Specifies the fully formatted SOAP message to transmit Contains the specific body content as required by the web service This block must contain a single element only.

Yes No No

Specifies the password associated with the <user-name> provided No

No Conditional Yes

Chapter 4 Additional base adapters

447

Web Services adapter requestmethod one

Figure 349 shows an XML sample of the adapter request for the Web Services adaptermethod one. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 349 XML sample of the Web Services actor adapter requestmethod one
<soap-rpc-request> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>true</allow-unsigned-certificate> <passphrase>changeit</passphrase> <http-connection-properties> <SoapAction>POST</SoapAction> </http-connection-properties> <transport>https-rpc</transport> <soap-url>https://test-machine:8080/sdk/vim </soap-url> <soap-message> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:vim2"> <soapenv:Header /> <soapenv:Body> <urn:RetrieveServiceContent> <urn:_this type="ServiceInstance">ServiceInstance</urn:_this> </urn:RetrieveServiceContent> </soapenv:Body> </soapenv:Envelope> </soap-message> </soap-rpc-request>

Figure 350 shows an XML sample of the adapter request with HTTPS Client Authentication for the Web Services adaptermethod one. Figure 350 XML sample of the Web Services actor adapter request with HTTPS Client Authenticationmethod one
<soap-rpc-request> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <truststore-file>C:\cacerts</truststore-file> <passphrase>changeit</passphrase> <keystore-file>C:\keystore.jks</keystore-file> <keystore-passphrase>changeit</keystore-passphrase> <client-alias>s1as</client-alias> <http-connection-properties> <SoapAction>POST</SoapAction> </http-connection-properties> <transport>https-rpc</transport> <soap-url>https://vm-w23-rds87:8181/CentralDataService/CentralData</soap-url> <soap-message> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.centraldata.com/"> <soapenv:Header /> <soapenv:Body> <ser:findReservations> <lastName>vorburger</lastName> </ser:findReservations> </soapenv:Body> </soapenv:Envelope> </soap-message> </soap-rpc-request>

448

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter requestmethod one

Figure 352 shows an XML sample of the adapter request with NTLM Authentication with HTTP support. Figure 351 XML sample of the Web Services actor adapter request with NTLM Authentication with HTTP support
<soap-rpc-request> <transport>http-rpc</transport> <soap-url>http://10.254.1.76:34663/_vti_bin/UserGroup.asmx</soap-url> <username>BMCDEV1\Administrator</username> <password>root@1233</password> <ntlm-authentication>true</ntlm-authentication> <http-connection-properties> <Content-Type>text/xml</Content-Type> <soapAction>http://schemas.microsoft.com/sharepoint/soap/directory/Get AllUserCollectionFromWeb</soapAction> </http-connection-properties> <soap-message> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:soap="http://schemas .xmlsoap.org/soap/envelope/"> <soap:Body> <GetAllUserCollectionFromWebxmlns="http://schemas.microsoft.com/sharepoint/s oap/directory/" /> </soap:Body> </soap:Envelope> </soap-message> </soap-rpc-request>

Figure 352 shows an XML sample of the adapter request with NTLM Authentication with HTTPS support. Figure 352 XML sample of the Web Services actor adapter request with NTLM Authentication with HTTPS support
<soap-rpc-request> <transport>https-rpc</transport> <soap-url>https://10.10.75.250/EWS/Exchange.asmx</soap-url> <username>BMCDEV\ntlm</username> <password>passw0rd#</password> <ntlm-authentication>true</ntlm-authentication> <http-connection-properties> <Content-Type>text/xml</Content-Type> </http-connection-properties> <soap-message> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetFolder xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"> </GetFolder> </soap:Body> </soap:Envelope> </soap-message> </soap-rpc-request>

Chapter 4 Additional base adapters

449

Web Services adapter responsemethod one

Web Services adapter responsemethod one

The Web Services actor adapter returns an adapter response that contains the full SOAP response to the adapter request. This response can be complex; You must have working knowledge of SOAP to use the response successfully. Figure 353 illustrates the adapter response for Web Services adaptermethod one. Figure 353 XML sample of the Web Services adapter responsemethod one
<soap-response> <metadata> <status>success</status> </metadata> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"> <soapenv:Body> <RetrieveServiceContentResponse xmlns="urn:vim2"> <returnval> <rootFolder type="Folder">group-d1</rootFolder> <propertyCollector type="PropertyCollector">propertyCollector</propertyCollector> <about> <name>VMware VirtualCenter</name> <fullName>VMware VirtualCenter 2.0.2 build-50618</fullName> <vendor>VMware, Inc.</vendor> <version>2.0.2</version> <build>50618</build> <localeVersion>INTL</localeVersion> <localeBuild>000</localeBuild> <osType>win32-x86</osType> <productLineId>vpx</productLineId> <apiType>VirtualCenter</apiType> <apiVersion>2.0.0</apiVersion> </about> <setting type="OptionManager">VpxSettings</setting> <userDirectory type="UserDirectory">UserDirectory</userDirectory> <sessionManager type="SessionManager">SessionManager</sessionManager> <authorizationManager type="AuthorizationManager">AuthorizationManager</authorizationManager> <perfManager type="PerformanceManager">PerfMgr</perfManager> <scheduledTaskManager type="ScheduledTaskManager">ScheduledTaskManager</scheduledTaskManager> <alarmManager type="AlarmManager">AlarmManager</alarmManager> <eventManager type="EventManager">EventManager</eventManager> <taskManager type="TaskManager">TaskManager</taskManager> <customizationSpecManager type="CustomizationSpecManager">CustomizationSpecManager</customizationSpecManager> <customFieldsManager type="CustomFieldsManager">CustomFieldsManager</customFieldsManager> <diagnosticManager type="DiagnosticManager">DiagMgr</diagnosticManager> <licenseManager type="LicenseManager">LicenseManager</licenseManager> <customFieldsManager type="CustomFieldsManager">CustomFieldsManager</customFieldsManager> <diagnosticManager type="DiagnosticManager">DiagMgr</diagnosticManager> <licenseManager type="LicenseManager">LicenseManager</licenseManager> <searchIndex type="SearchIndex">SearchIndex</searchIndex> </returnval> </RetrieveServiceContentResponse> </soapenv:Body> </soapenv:Envelope> </soap-response>

450

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter responsemethod one

Figure 354 illustrates the adapter response for Web Services adapter with HTTPS Client Authentication- method one. Figure 354 XML sample of the Web Services adapter response with Client Authenticationmethod one
<soap-response> <metadata> <status>success</status> </metadata> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:findReservationsResponse xmlns:ns2="http://service.centraldata.com/"> <return> <confNumber>0004</confNumber> <firstName>Mike</firstName> <lastName>Vorburger</lastName> </return> </ns2:findReservationsResponse> </S:Body> </S:Envelope> </soap-response>

Figure 356 illustrates the adapter response for Web Services adapter with NTLM authentication with HTTP support. Figure 355 XML sample of the Web Services adapter response with NTLM authentication with HTTP support
<adapter-response> <data> <soap-response> <soap:Envelope> <soap:Body> <GetAllUserCollectionFromWebResponse> <GetAllUserCollectionFromWebResult> <GetAllUserCollectionFromWeb> <Users> <User ID="8786" Sid="S-1-5-21-935981524-3360503449-101602611109847" Name="Weissban, Anat" LoginName="ADPROD\aweissba" Email="" Notes="" IsSiteAdmin="False" IsDomainGroup="False" /> <User ID="3815" Sid="S-1-5-21-935981524-3360503449-10160261142852" Name="Weiss, Christian" LoginName="ADPROD\cweiss" Email="Christian_Weiss@abc.com" Notes="" IsSiteAdmin="False" IsDomainGroup="False" /> </Users> </GetAllUserCollectionFromWeb> </GetAllUserCollectionFromWebResult> </GetAllUserCollectionFromWebResponse> </soap:Body> </soap:Envelope> </soap-response> </data> </adapter-response>

Chapter 4 Additional base adapters

451

Web Services adapter requestmethod two

Figure 356 illustrates the adapter response to the Web Services adapter request with NTLM authentication and HTTPS support. Figure 356 XML sample of the Web Services adapter response with NTLM authentication with HTTPS support
<soap-response> <metadata> <status>success</status> </metadata> <soap11:Body> <detail> <e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorSchemaValidatio n</e:ResponseCode>.* <e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">The element 'GetFolder' in namespace 'http://schemas.microsoft.com/exchange/services/2006/messages' has incomplete content. List of possible elements expected: 'FolderShape' in namespace 'http://schemas.microsoft.com/exchange/services/2006/messages'.</e:Message> <e:Line xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">1</e:Line>. <e:Position xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">353</e:Position> </detail> </soap11:Body> </soap-response>

Web Services adapter requestmethod two

This method includes the persistent connectivity feature available for terminal adapters. This method supports connection through proxy server. The proxy settings provided with the adapter request override the configuration proxy settings. When you create the adapter request in the Transform Editor, you must enclose this template within <request-data> tags. BMC recommends that you do not include empty elements in the adapter request because they might cause errors. Table 153 describes the adapter request elements for the Web Services adapter method two. Table 153 Web Services adapter requestmethod two elements (part 1 of 2)
Element <soap-url> <user-name> <password> <soap-action> <soap-version> Description Specifies the URL for the remote SOAP service Specifies the user name for HTTP basic authentication Specifies the password associated with the <user-name> provided Specifies the action to be performed by the SOAP request Specifies the SOAP version to use Valid values: 1.1 (default), 1.2 Required Yes No No No No

452

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter requestmethod two

Table 153 Web Services adapter requestmethod two elements (part 2 of 2)

Element <connection> <name> Description Contains the named connection elements Specifies the reference name for the connection This reference name is used in subsequent requests in a process to maintain the connection and session cookies. This element is required when the <connection> element is present. <terminate-onexit> Closes the connection and clears session cookies upon completion of a No request Valid values: true, false (default) <soap-headercontent> <soap-bodycontent> <chunkedencoding> <proxysettings> <host> Contains the specific header content as required by the web service This can contain zero or more elements. Contains the specific body content as required by the web service This block must contain a single element only. Specifies whether chunked transfer encoding is enabled or disabled Valid values: true, false Contains the elements that define the HTTP proxy settings Specifies the host name or the IP address of the host for the Web service request This element is required if the <proxy-settings> element is used. <port> Specifies the destination port for the Web service request This element is required if the <proxy-settings> element is used. <user-name> Specifies the name of the user, who requests the proxy service This element is required if the <proxy-settings> element is used and authentication is enabled and necessary on the proxy server. <password> Specifies the password for the user on the specified host This element is required if <proxy-settings> is used and authentication is enabled and necessary on the proxy server. Conditional Conditional Conditional No Conditional No Yes No Required No Conditional

Figure 357 shows an XML template of the adapter request for the Web Services adaptermethod two.

Chapter 4 Additional base adapters

453

Web Services adapter responsemethod two

Figure 357 XML template of the Web Services adapter requestmethod two
<soap-rpc-request> <soap-url></soap-url> <user-name></user-name> <password></password> <soap-action></soap-action> <soap-version></soap-version> <connection> <name></name> <terminate-on-exit></terminate-on-exit> </connection> <soap-header-content> <></> </soap-header-content> <soap-body-content> <></> </soap-body-content> </soap-rpc-request>

Figure 358 shows an XML sample of the adapter request for the Web Services adaptermethod two. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 358 XML sample of the Web Services adapter requestmethod two
<soap-rpc-request> <soap-url>http://www.webservicemart.com/uszip.asmx</soap-url> <soap-action>http://webservicemart.com/ws/ValidateZip</soap-action> <soap-body-content> <ws:ValidateZip xmlns:ws="http://webservicemart.com/ws/"> <ws:ZipCode>94041</ws:ZipCode> </ws:ValidateZip> </soap-body-content> </soap-rpc-request>

Web Services adapter responsemethod two

The Web Services adapter returns an adapter response that contains the header and body content from the SOAP response to the adapter request.

454

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter requestJAX-WS Approach

Figure 359 illustrates an XML sample of the adapter response for the Web Services adapter -method two. Figure 359 XML sample of the Web Services adapter response
<soap-response> <metadata> <status>success</status> </metadata> <response> <soap-header-content /> <soap-body-content> <ValidateZipResponse xmlns="http://webservicemart.com/ws/"> <ValidateZipResult><result code="200"><item zip="94041" state="CA" latitude ="37.38949" longitude ="-122.07846"/></result></ValidateZipResult> </ValidateZipResponse> </soap-body-content> </response> </soap-response>

Web Services adapter requestJAX-WS Approach

The JAX-WS approach supports dynamic invocation of service endpoint operations as follows:
s

Make SOAP Request Payload mode Make SOAP Request Message mode Poll Asynchronous Response

This method supports connection through proxy server. The proxy settings provided with the adapter request override the configuration proxy settings.

Web Services adapter request for Make SOAP Request Payload mode
In the Make SOAP Request Payload mode, the client provides the contents of the <soap:Body> element and JAX-WS includes the input payload in the <soap:Envelope> element. Figure 360 shows an XML sample of the adapter request for the Web Services adapter with synchronous invocation of the Make SOAP RequestPayload mode.

Chapter 4 Additional base adapters

455

Web Services adapter response for Make SOAP RequestPayload mode

Figure 360 XML sample of the Web Services adapter requestMake SOAP RequestPayload mode
<soap-rpc-request> <wsdl-location>http://localhost:6680/baocdp/orca?wsdl</wsdl-location> <authentication>Username-Token</authentication> <username>admin</username> <password encryption-type="Base64">YWRtaW4xMjM=</password> <password-type>plain-text</password-type> <invocation-mode>synchronous</invocation-mode> <soap-body-content> <soa:getProcessDescription xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa"> <soa:gridName>DevGrid</soa:gridName> <soa:processName>:Test_Module:Test</soa:processName> </soa:getProcessDescription> </soap-body-content> </soap-rpc-request>

Web Services adapter response for Make SOAP Request Payload mode
The Web Services adapter returns a SOAP response for Make SOAP Request Payload mode. Table 154 describes the adapter request elements for the Web Services adapter with the Payload mode. Table 154 Web Services adapter request JAX-WS methodPayload mode elements (part 1 of 2)
Element <wsdl-location> <soap-bodycontent> <service-name> Description Specifies the URI (filename or URL) pointing to a WSDL XML definition Contains the specific body content as required by the web service This block must contain a single element only. Specifies a unique name among all the services defined within the enclosing WSDL document A service groups a set of related ports together. <port-name> Specifies a unique name among all the ports defined within the enclosing WSDL document A port defines an individual endpoint by specifying a single address for a binding. <soap-action> <user-name> <password> <authentication> Specifies the value of the SOAPAction header for the operation Specifies the user name for authentication Specifies the password for authentication Specifies the types of authentication supported by the adapter Valid values: basic (default), username-token No No No No No No Required Yes Yes

456

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter response for Make SOAP RequestPayload mode

Table 154 Web Services adapter request JAX-WS methodPayload mode elements (part 2 of 2)
Element <password encryption-type> Description Specifies the method of encryption used to encrypt the given password Valid values: Base64, Plain (default) Note: This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted. If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. <password type> Specifies the type of password supported for username-token authentication Valid values: plain-text (default), digest Note: This parameter is required only if the value of the <authentication> element is username-token. <invocation-mode> Specifies the way in which a web service request is invoked Valid values: synchronous (default), asynchronous, one-way <proxy-settings> <host> Contains the elements that define the HTTP proxy settings Specifies the host name or the IP address of the host for the Web service request This element is required if the <proxy-settings> element is used. <port> Specifies the destination port for the Web service request This element is required if the <proxy-settings> element is used. <user-name> Specifies the name of the user, who requests the proxy service This element is required if the <proxy-settings> element is used and authentication is enabled and necessary on the proxy serve.r <password> Specifies the password for the user on the specified host This element is required if <proxy-settings> is used and authentication is enabled and necessary on the proxy server. Conditiona l Conditiona l Conditiona l No Conditiona l No No Required No

Chapter 4 Additional base adapters

457

Web Services adapter request for Make SOAP RequestMessage mode

Figure 361 illustrates the adapter response for the Web Services adapter request with Make SOAP Request in synchronous Payload mode. Figure 361 XML sample of the Web Services adapter response to a request for Make SOAP Request Payload mode
<soap-response> <metadata> <status>success</status> </metadata> <ns1:getProcessDescriptionResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa"> <ns1:Description> <ns1:Name>:Test_Module:Test</ns1:Name> <ns1:PeerLocation>ANY</ns1:PeerLocation> <ns1:Description>This is description for test process.</ns1:Description> <ns1:Parameters> <ns1:Output> <ns1:Parameter> <ns1:Name required="false">output</ns1:Name> <ns1:Description>This is the description for a test process.</ns1:Description> </ns1:Parameter> </ns1:Output> </ns1:Parameters> </ns1:Description> </ns1:getProcessDescriptionResponse> </soap-response>

Web Services adapter request for Make SOAP Request Message mode
In the Message mode, the client can either provide the entire SOAP envelope or the SOAP body payload as required by the web service. This method supports signing SOAP messages according to the Web Services Security (WSS) specification to assure the integrity of the SOAP message and allows the communication of the X.509 security token format. Signed messages also provide non-repudiation. This method also supports UsernameToken Profile authentication that defines how a web service consumer can supply a UsernameToken to identify the requestor using a username and a password to authenticate that identity to the web service producer.

458

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter request for Make SOAP RequestMessage mode

Table 155 describes the elements for the Web Services adapter request for Make SOAP in the Message mode. Table 155 Elements in the Web Services adapter request for Make SOAP request with JAX-WS method in Message mode (part 1 of 4)
Element <wsdllocation> <soapmessage> <endpointaddress> Description Specifies the URI (file name or URL) pointing to a XML WSDL definition Specifies the fully formatted SOAP message to transmit Specifies the target service endpoint address This element can be used if the SOAP request must be invoked on an endpoint address other than the one specified in the WSDL document. <servicename> Specifies a unique name among all the services defined within the enclosing WSDL document A service groups a set of related ports together. <port-name> Specifies a unique name among all the ports defined within the enclosing WSDL document A port defines an individual endpoint by specifying a single address for a binding. <soap-action> Specifies the value of the SOAPAction header for the operation <soapversion> <use-sslcertificate> <installcertificate> <allowunsignedcertificate> <truststorefile> <passphrase> Specifies the SOAP version to use Valid values: 1.1 (default), 1.2 Specifies whether to establish a secure connection Valid values: true, false (default) Specifies whether to install certificates Valid values: true, false (default) Specifies whether to allow unsigned certificates from trusted zones Default value: false Specifies the path to the truststore file containing the CAs Default value: Java standard truststore Specifies the password of the truststore file Default value: changeit <keystorefile> <keystorepassphrase> Specifies the path to the keystore containing the client certificate Specifies the path to the keystore containing the client certificate Default value: changeit No No No No No No No No No No No Required Yes Yes No

Chapter 4 Additional base adapters

459

Web Services adapter request for Make SOAP RequestMessage mode

Table 155 Elements in the Web Services adapter request for Make SOAP request with JAX-WS method in Message mode (part 2 of 4)
Element <clientalias> <usernametoken> Description Specifies the alias name in the keystore that identifies the public key certificate (PKC) used by the web server to authenticate the client Builds a Web Services username token and inserts it into the SOAP envelope Valid values: true, false <username> <password> <password encryptiontype> Specifies the user name for authentication Specifies the password for authentication No No Required No No

Specifies the method of encryption used to encrypt the given password No Valid values: Base64, Plain (default) Note: This element can contain an encryption-type attribute to indicate whether the passphrase provided is encrypted. If the <password encryption-type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text.

<passwordtype>

Specifies the types of password supported by username-token authentication This parameter is read-only if the value of the <username-token> element is true. Valid values: plain-text (default), digest

No

<timestamp>

Builds a Web Services timestamp and inserts it into the SOAP envelope No Valid values: true, false (default)

<time-tolive>

Sets the time difference in seconds between the Created and the Expires No values in the timestamp Default value: 60 seconds

<noncevalidation> <createdvalidation> <signrequest>

Adds a nonce element to the username-token Valid values: true, false (default) Adds a created element to the username-token Valid values: true, false (default) Creates a signature according to Web Services specification, X.509 profile, and adds it to the Security header The Token Reference supported by the adapter is Binary Security Token. Valid values: true, false (default)

No

No

No

460

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter request for Make SOAP RequestMessage mode

Table 155 Elements in the Web Services adapter request for Make SOAP request with JAX-WS method in Message mode (part 3 of 4)
Element <signatureproperties> Description Contains the elements used to specify the information about the X.509 certificate (Public Key) and the Private Key that are used for XML Digital Signature Valid values for the mode attribute: key-store (default), key-files, and key-data <signusernametoken> <signtimestamp> Signs the Web Services <username-token> element in the Security header Valid values: true, false (default) Signs the Web Services timestamp element in the Security header Valid values: true, false (default) <private-key- Specifies the file containing the Private Key used to sign the SOAP file> message using the signing algorithm The adapter supports the following formats:
s s

Required No

No

No

Conditional

Base64-encoded unencrypted Privacy Enhanced Mail (PEM) Definite Encoding Rules (DER)

This element is required if the value of the mode attribute of the <signature-properties> element is key-files. <certificate- Specifies the file containing the X.509 certificate (public key) file> The adapter supports the following formats:
s s

Conditional

Base64-encoded unencrypted Privacy Enhanced Mail (PEM) Definite Encoding Rules (DER)

This element is required if the value of the mode attribute of the <signature-properties> element is key-files. <private-key- Specifies the private key in unencrypted Base64-encoded PEM format data> This element is required if the value of the mode attribute of the <signature-properties> element is key-data. <certificate- Specifies the X.509 certificate (public key) in unencrypted Base64data> encoded PEM format This element is required if the value of the mode attribute of the <signature-properties> element is key-data. Conditional

Conditional

Chapter 4 Additional base adapters

461

Web Services adapter request for Make SOAP RequestMessage mode

Table 155 Elements in the Web Services adapter request for Make SOAP request with JAX-WS method in Message mode (part 4 of 4)
Element <keystorefile> Description Configures the adapter to use the Java keystore (JKS) specified by the keystore file name The adapter must contain the absolute path of the keystore file. This element is required if the value of the mode attribute of the <signature-properties> element is key-store. <keystorepassword> Specifies the password of the keystore This element is required if the value of the mode attribute of the <signature-properties> element is key-store. <alias> Specifies the user's alias name in the keystore that identifies the private key to sign the document This element is required if the value of the mode attribute of the <signature-properties> element is key-store. <password> <invocationmode> <proxysettings> <host> Specifies the user's password to get the private signing key from the keystore Specifies the ways in which a web service request can be invoked Valid values: synchronous (default), asynchronous, one-way Contains the elements that define the HTTP proxy settings No No No Conditional Conditional Required Conditional

Specifies the host name or the IP address of the host for the Web service Conditional request This element is required if the <proxy-settings> element is used.

<port>

Specifies the destination port for the Web service request This element is required if the <proxy-settings> element is used.

Conditional

<user-name>

Specifies the name of the user, who requests the proxy service This element is required if the <proxy-settings> element is used and authentication is enabled and necessary on the proxy server.

Conditional

<password>

Specifies the password for the user on the specified host This element is required if <proxy-settings> is used and authentication is enabled and necessary on the proxy server.

Conditional

Figure 362 shows an XML sample of the Web Services adapter request with the synchronous Message mode and using username-token authentication with a Base64 encoded password and X.509 digital signature authentication. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

462

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter request for Make SOAP RequestMessage mode

Figure 362 XML sample of the Web Services adapter request for Make SOAP Request in Message mode and using username-token and X.509 digital signature authentication
<soap-rpc-request> <wsdl-location>http://vm-w23-rds19:9090/atriumversions_porttype?wsdl</wsdl-location> <username-token>true</username-token> <username>Demo</username> <password encryption-type="Base64"> IA== </password> <password-type>plain-text</password-type> <nonce-validation>true</nonce-validation> <created-validation>true</created-validation> <sign-request>true</sign-request> <signature-properties mode="keystore"> <sign-username-token>true</sign-username-token> <sign-timestamp /> <keystore-file>C:\Security\bmcatriumwsclient_7.5.00.001.jks</keystore-file> <keystore-password>atrium</keystore-password> <alias>bmcatriumwsclient</alias> </signature-properties> <invocation-mode>synchronous</invocation-mode> <soap-message> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header /> <soapenv:Body> <typ:GetVersions> xmlns:typ="http://atrium.bmc.com/2009/01/versions/types"> <appIdList> <list>OB00C04FA081BABZlxQAmyflAg1wEA</list> </appIdList> </typ:GetVersions> </soapenv:Body> </soapenv:Envelope> </soap-message> </soap-rpc-request>

Figure 363 shows an XML sample of the Web Services adapter request for Make SOAP Request with the synchronous Message mode and using a timestamp and X.509 digital signature authentication. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 363 XML sample of the Web Services adapter request for Make SOAP Request in Message mode and using timestamp and X.509 digital signature authentication
<wsdl-location>http://s3.amazonaws.com/ec2-downloads/2009-10-31.ec2.wsdl</wsdl-location> <timestamp>true</timestamp> <time-to-live>30</time-to-live> <sign-request>true</sign-request> <signature-properties mode="key-files"> <sign-username-token /> <sign-timestamp>true</sign-timestamp> <private-key-file>C:\Security\private-key.der</private-key-file> <certificate-file>C:\Security\certificate.der</certificate-file> </signature-properties> <invocation-mode>synchronous</invocation-mode> <soap-message> <web:DescribeSecurityGroups xmlns:web="http://ec2.amazonaws.com/doc/2009-10-31/"> <web:securityGroupSet /> </web:DescribeSecurityGroups> </soap-message> </soap-rpc-request>

Chapter 4 Additional base adapters

463

Web Services adapter request for Make SOAP RequestMessage mode

Figure 364 shows the Web Services adapter request for Make SOAP Request with HTTPS client authentication. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 364 XML sample of the Web Services adapter request for Make SOAP Request in Message mode with HTTPS client authentication
<soap-rpc-request> <wsdl-location>https://vm-w23-rds87:8181/CentralDataService/CentralData?wsdl</wsdllocation> <invocation-mode>synchronous</invocation-mode> <use-ssl-certificate>true</use-ssl-certificate> <install-certificate>true</install-certificate> <allow-unsigned-certificate>false</allow-unsigned-certificate> <truststore-file>C:\Rohit\cacerts.jks</truststore-file> <passphrase>changeit</passphrase> <keystore-file>C:\keystore.jks</keystore-file> <keystore-passphrase>changeit</keystore-passphrase> <client-alias>s1as</client-alias> <soap-message> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.centraldata.com/"> <soapenv:Header/> <soapenv:Body> <ser:findReservations> <lastName>Doe</lastName> </ser:findReservations> </soapenv:Body> </soapenv:Envelope> </soap-message> </soap-rpc-request>

464

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter response for Make SOAP RequestMessage mode

Web Services adapter response for Make SOAP Request Message mode
The Web Services adapter returns a SOAP response. Figure 365 illustrates the Web Services adapter response to a request for Make SOAP Request with synchronous Message mode and using username token and X.509 digital signature authentication. Figure 365 XML sample of the Web Services adapter responseMake SOAP Request in Message mode and using username token and X.509 digital signature authentication
<soap-response> <metadata> <status>success</status> </metadata> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header /> <SOAP-ENV:Body> <GetVersionsOutput xmlns="http://atrium.bmc.com/2009/01/versions/types"> <versionInfoList xmlns=""> <list> <applicationId>OB00C04FA081BABZlxQAmyflAg1wEA</applicationId> <applicationName>BMC Atrium CMDB</applicationName> <maintenanceVer>0</maintenanceVer> <majorVer>7</majorVer> <minorVer>5</minorVer> <patchNum>3</patchNum> <isExist>true</isExist> </list> </versionInfoList> <status xmlns="" /> <extensions xmlns="" xsi:nil="true" /> </GetVersionsOutput> </SOAP-ENV:Body> </SOAP-ENV:Envelope> </soap-response>

Chapter 4 Additional base adapters

465

Web Services adapter response for Make SOAP RequestMessage mode

Figure 366 illustrates an XML sample of the adapter response for the Web Services adapter request for Make SOAP Request in Message mode and using timestamp and X.509 digital signature authentication. Figure 366 XML sample of the Web Services adapter response to a request for Make SOAP Request in Message mode and using timestamp and X.509 digital signature authentication
<soap-response> <metadata> <status>success</status> </metadata> <DescribeSecurityGroupsResponse xmlns="http://ec2.amazonaws.com/doc/2009-10-31/"> <requestId>29b3f7ee-93ab-43e9-a7d1-4894881f2ef3</requestId> <securityGroupInfo> <item> <ownerId>622872856407</ownerId> <groupName>usersec</groupName> <groupDescription>first AMI</groupDescription> <ipPermissions> <item> <ipProtocol>tcp</ipProtocol> <fromPort>22</fromPort> <toPort>22</toPort> <groups /> <ipRanges> <item> <cidrIp>0.0.0.0/0</cidrIp> </item> </ipRanges> </item> <item> <ipProtocol>tcp</ipProtocol> <fromPort>80</fromPort> <toPort>80</toPort> <groups /> <ipRanges> <item> <cidrIp>0.0.0.0/0</cidrIp> </item> </ipRanges> </item> <item> <ipProtocol>tcp</ipProtocol> <fromPort>3389</fromPort> <toPort>3389</toPort> <groups /> <ipRanges> <item> <cidrIp>0.0.0.0/0</cidrIp> </item> </ipRanges> </item> </ipPermissions> </item> <item> <ownerId>622872856407</ownerId> <groupName>Test Security Group - 2</groupName> <groupDescription>test</groupDescription> <ipPermissions /> </item> </securityGroupInfo> </DescribeSecurityGroupsResponse> </soap-response>

466

BMC Atrium Orchestrator Base Adapters User Guide

Web Services adapter request for Poll Asynchronous Response

Figure 367 illustrates an XML sample of the Web Services adapter response to a request for the Make SOAP Request in Message mode with HTTPS client authentication. Figure 367 XML sample of the Web Services adapter response to a request for Make SOAP Request in Message mode with HTTP client authentication
<metadata> <status>success</status> </metadata> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Header /> <S:Body> <ns2:findReservationsResponse xmlns:ns2="http://service.centraldata.com/"> <return> <confNumber>0001</confNumber> <firstName>John</firstName> <lastName>Doe</lastName> </return> <return> <confNumber>0002</confNumber> <firstName>Jane</firstName> <lastName>Doe</lastName> </return> </ns2:findReservationsResponse> </S:Body> </S:Envelope> </soap-response>

Web Services adapter request for Poll Asynchronous Response

Poll Asynchronous Response is used when a service operation is invoked asynchronously. The results of the operation are obtained by polling the returned response. Table 156 describes the element for the Web Services adapter request for Poll Asynchronous Response. Table 156 Element for Web Services adapter request with Poll Asynchronous Response
Element <requestname> Description Specifies the name where the response to the asynchronous request is stored in the cache Required Yes

Figure 368 shows an XML sample of the Web Services adapter request with Poll Asynchronous Response. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Chapter 4 Additional base adapters

467

Web Services adapter response for a request with Poll Asynchronous Response

Figure 368 XML sample of the Web Services adapter requestPoll Asynchronous Response
<soap-rpc-request> <request-name>MESSAGE-REQUEST-4</request-name> </soap-rpc-request>

Web Services adapter response for a request with Poll Asynchronous Response
Figure 369 illustrates an XML sample of the adapter response for the Web Services adapter response with Poll Asynchronous Response. Figure 369 XML sample of the Web Services adapter response with Poll Asynchronous Response
<soap-response> <metadata> <status>success</status> </metadata> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Header /> <S:Body> <ns1:getProcessDescriptionResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa"> <ns1:Description> <ns1:Name>:Test_Module:Test</ns1:Name> <ns1:PeerLocation>ANY</ns1:PeerLocation> <ns1:Description>This is description for test process.</ns1:Description> <ns1:Parameters> <ns1:Output> <ns1:Parameter> <ns1:Name required="false">output</ns1:Name> <ns1:Description>This is description for test process.</ns1:Description> </ns1:Parameter> </ns1:Output> </ns1:Parameters> </ns1:Description> </ns1:getProcessDescriptionResponse> </S:Body> </S:Envelope>

</soap-response>

468

BMC Atrium Orchestrator Base Adapters User Guide

Differences in the methods used to define a Web Services adapter request

Differences in the methods used to define a Web Services adapter request

Table 157 describes the basic differences between methods for defining a Web Services adapter request. Table 157 Differences between method one, method two, and JAX-WS approach
Method One Requires transport type Method Two Does not require transport type because it is handled by the SOAP stack Requires a header and body payload JAX-WS approach Does not require transport type because it is handled by the JAXWS stack Supports SOAP envelope and body payload Uses JAX-WS 2.1 libs Supports synchronous, asynchronous, and one-way invocation

Requires a complete SOAP envelope

Uses JDK libs and does not require Uses Axis 1.4 libs third-party libraries for invocation Supports synchronous invocation only Supports transport level encryption through SSL and HTTPS Supports synchronous invocation only

Supports basic authentication (user Supports basic authentication, Web name and password) Services Security (username token profile and X.509 certificate token profile authentication) and transport level encryption through SSL and HTTPS

Chapter 4 Additional base adapters

469

Differences in the methods used to define a Web Services adapter request

470

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

5
471 472 472 477 478 479 479 486 489 489 497

Mail adapters
This chapter presents the following topics: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SMTP adapter response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMAP mail adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMAP mail configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMAP mail monitor event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POP mail adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POP mail adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POP mail event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction
Mail adapters are used to provide integration with mailboxes. You can use the SMTP adapter to send emails to notify about an action, or the IMAP/POP adapter to monitor or notified about a particular event using an email on a configured mailbox. The mail adapters are capable of communicating over SSL channel also provide functionality for sending and downloading mail attachments. This document describes the use and features of the following mail adapters:
s s s

SMTP IMAP POP

Chapter 5 Mail adapters

471

SMTP adapter

SMTP adapter
The SMTP adapter sends email messages through a configured SMTP server. This adapter does not support multiple configuration nodes, but you can configure multiple SMTP adapters within Grid Manager, each with a unique configuration node and adapter name. This section describes the configuration, request format, and response format of the SMTP adapter:

SMTP adapter configuration

SMTP adapter request

SMTP adapter configuration

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-smtp[version] Default adapter name: SMTPAdapter To configure the SMTP adapter, see Configuring the adapter on page 14. Table 158 describes the adapter configuration elements for the SMTP adapter that you can specify by 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. Table 158 Configuration node elementsSMTP adapter (part 1 of 4)
UI Label Target Port Element <target> <port> Description Required Specifies the host name or the IP address of the SMTP Yes server Specifies the port on which the SMTP server listens If the value of the <use-ssl-certificate> element is false, the default value is 25. Else, if the value of the <use-ssl-certificate> element is true, the default value is 465. Authenticate <authenticate> Indicates if the adapter must authenticate with the server before sending an email message Valid values: true, false (default) No No

472

BMC Atrium Orchestrator Base Adapters User Guide

SMTP adapter configuration

Table 158 Configuration node elementsSMTP adapter (part 2 of 4)

UI Label User Name Element <user-name> Description Specifies the user name to be used for authentication This element is required only when the value of the <authenticate> element is true. When the value of the <authenticate> element is false, any value present in this element is ignored. Password <password> Specifies the password that corresponds to the <user-name> provided This element is required only when the value of the <authenticate> element is true. When the value of the <authenticate> element is false, any value present in this element is ignored. Javamail Debug <javamaildebug> Indicates whether debug message logging for JavaMail must be turned on Valid values: true, false Default value: false Disable Mail Interaction <disable-mail- Signals the SMTP server that email messages must not No interaction> be sent This element can be used for testing Valid values: true, false (default) Starttls <starttls> Indicates that the SMTP server requires a STARTTLS command to be sent when sending email message Valid values: true, false (default) Max Attachment Size <maxattachmentsize> Specifies the maximum file size, in MB, which can be attached to a mail message The maximum file size is defined per attachment; the total value of all the files can be greater, provided each file is less than or equal to the default value Default value: 10 MB File Name Filter <file-namefilter> Contains the elements that specify the file name criteria for a file attachment You can attach only those files that satisfy the filter criteria. This element is required if the <file-name> element is present Conditional No No No Conditional Required Conditional

Chapter 5 Mail adapters

473

SMTP adapter configuration

Table 158 Configuration node elementsSMTP adapter (part 3 of 4)

UI Label File Name Element <file-name> Description Specifies the criteria for file attachment, based on the file name You can define one or more file names. A file that matches at least one file name filter is attached. If you do not provide a criteria, a file with any file name is attached. You can use wildcard characters, * and ? to define the file name filter. With a *, the wild card portion of the file name can contain an unlimited number of characters. With a ?, there is a one-to-one relationship between the ? and the file name character. File Type Filter <file-typefilter> Contains the elements that specify the file type criteria Conditional for a file attachment You can attach only those files that satisfy the filter criteria. This element is required if the <file-type> element is present. File Type <file-type> Specifies the criteria for file attachment, based on the file type You can define one or more file types. A file that matches at least one file type filter is attached. If you do not provide a criteria, a file with any file type is attached. Valid values: DOC, XLS, XML, PDF, HTML, EXE Use Ssl Certificate <use-sslcertificate> Specifies whether SSL certificates are used for authentication Valid values: true, false (default) Allow Unsigned Certificates <allowunsignedcertificates> Specifies whether unsigned certificates are permitted for SSL authentication This element is ignored if the value of the <use-sslcertificate> element is false Valid values: true, false (default) No No No Required No

474

BMC Atrium Orchestrator Base Adapters User Guide

SMTP adapter configuration

Table 158 Configuration node elementsSMTP adapter (part 4 of 4)

UI Label Install Certificate Element <installcertificate> Description Updates the default keystore file, java.Home\jre\lib\security\cacerts with the certificates sent by the target URL during the SSLHandshake This element is ignored if the value of the <use-sslcertificate> element is false. If the verification of a certificate fails, the certificate is not installed. To install certificates successfully, the user who installs the peer that executes the request must have read or write access to the keystore file. Certificates are uninstalled when the adapter is disabled on a peer. If a BMC Atrium Orchestrator peer is uninstalled without disabling this adapter, any certificates installed by the adapter continue to exist. The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled. Valid values: true, false (default) Passphrase <passphrase> Specifies the passphrase that is used to install certificates for the keystore file This element is ignored if the value of the <use-sslcertificate> element is false. This value must match the passphrase in the keystore. You can change the passphrase using keytool. If you make a change, you must update this value to reflect the new passphrase. Default value: changeit No Required No

NOTE
The SMTP mail adapter supports the following message formats for the content of an email:
s s s

Plain text Rich text HTML

Chapter 5 Mail adapters

475

SMTP adapter configuration

Figure 370 shows an XML template of the adapter configuration for the SMTP adapter. Figure 370 XML template of the SMTP adapter configuration
<config> <target></target> <port></port> <authenticate></authenticate> <user-name></user-name> <password></password> <javamail-debug></javamail-debug> <disable-mail-interaction></disable-mail-interaction> <starttls></starttls> <max-attachment-size></max-attachment-size> <file-name-filter> <file-name></file-name> <file-name></file-name> </file-name-filter> <file-type-filter> <file-type></file-type> <file-type></file-type> </file-type-filter> <use-ssl-certificate></use-ssl-certificate> <allow-unsigned-certificate></allow-unsigned-certificate> <install-certificate></install-certificate> <passphrase></passphrase> </config>

Figure 371 shows an XML sample of the SMTP adapter configuration. Figure 371 XML sample of the SMTP adapter configuration
<config> <target>smtp.runbox.com</target> <authenticate>true</authenticate> <user-name>user1</user-name> <password>1234</password> <port>26</port> </config>

Figure 372 shows an XML sample of the SMTP adapter configuration with <maxattachment-size>. Figure 372 XML sample of the SMTP adapter configuration with <max-attachment-size>
<config> <target>smtp.runbox.com</target> <port>26</port> <max-attachment-size>1</max-attachment-size> </config>

476

BMC Atrium Orchestrator Base Adapters User Guide

SMTP adapter request

SMTP adapter request

The SMTP adapter does not use an action. You must leave the adapters Action field blank in the Properties tab of the Property panel of the Call Adapter activity in BMC Atrium Orchestrator Development Studio. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. When the adapter request is formed in the Advanced Transform Editor, the template must be enclosed in <request-data> tags. Table 159 describes the adapter request elements for the SMTP adapter. Table 159 Adapter request elements SMTP adapter
Element <to> Description Required Specifies one or more address nodes, each containing the email address of Yes a primary recipient You must provide at least one address. <cc> <subject> <from> <body> Specifies one or more address nodes, each containing the email address of No a courtesy copy recipient Specifies the subject line for the email message Specifies the email address of the message sender Specifies the body text for the email message Yes Yes Yes Conditional

<attachment Contains the <attachment> elements s> This element is required if the <attachment> element is present. <attachment Specifies the full path and file name of the file to be attached to the mail > message You can define one or more <attachment> elements. The file to be attached must reside on the peer executing the adapter request.

No

Figure 373 shows an XML template of the adapter request for the SMTP adapter. Figure 373 XML template of the SMTP adapter request
<smtp-request> <to> <address></address> </to> <cc> <address></address> </cc> <subject></subject> <from></from> <body></body> <attachments> <attachment></attachment> </attachments> </smtp-request>

Chapter 5 Mail adapters

477

SMTP adapter response

Figure 374 shows an XML sample of the adapter request for the SMTP adapter. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 374 XML sample of the SMTP adapter request
<smtp-request> <to> <address>user1@runbox.com</address> </to> <cc> <address>user2@runbox.com</address> </cc> <subject>Automation Subject Line</subject> <from>AutomationAdmin@bmc.com</from> <body>Message body</body> </smtp-request>

Figure 375 shows an XML sample of the adapter request for the SMTP adapter with attachment support. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 375 XML sample of the SMTP adapter request with attachment support
<smtp-request> <to> <address>aa@runbox.com</address> </to> <subject>New Testing Testing</subject> <from>bbb@gic.com</from> <body>New Message body</body> <attachments> <attachment>C:\testFile1.txt</attachment> <attachment>C:\testFile2.txt</attachment> </attachments> </smtp-request>

SMTP adapter response

The SMTP adapter request returns a response that indicates the status of the request. Table 160 describes the adapter response elements for the SMTP adapter. Table 160 Adapter response elementsSMTP adapter
Element <metadata> <status> Description Contains the <status> elements Indicates the status of the adapter request Valid values: success, error <error> Specifies the error message returned when the value of the <status> element is error

478

BMC Atrium Orchestrator Base Adapters User Guide

IMAP mail adapter

Figure 376 illustrates an XML sample of the adapter response for the SMTP adapter. Figure 376 XML sample of the SMTP adapter response
<smtp-response> <metadata> <status>success or error</status> <error>error message returned, present only with a status of error</error> </metadata> </smtp-response>

IMAP mail adapter

The Internet Message Access Protocol (IMAP) mail adapter checks for messages in a specified account on an IMAP mail server. The account information is designated in the configuration node for the adapter in Grid Manager. This adapter does not support multiple configuration nodes, but you can configure multiple IMAP mail adapters within Grid Manager, each with a unique configuration node and adapter name. This section describes the following configuration and event formats of the IMAP mail adapter:

IMAP mail configuration

IMAP mail monitor event

IMAP mail configuration

The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled. BMC recommends that you do not include unused elements in the adapter request because they might cause errors. Adapter type: ro-adapter-imap[version] To configure the IMAP mail adapter, see Configuring the adapter on page 14 Table 161 on page 480 describes the adapter configuration elements for the IMAP mail adapter that you can specify by 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.

Chapter 5 Mail adapters

479

IMAP mail configuration

Table 161 IMAP mail adapter configuration node elements (part 1 of 5)

UI label Target Port Element <target> <port> Description Required Specifies the host name or the IP address of the IMAP Yes server Specifies the port on which the IMAP server listens If not provided, a default value is assigned. If the value of the <use-ssl-certificate> element is false, the default value is 143. If the value of the <use-ssl-certificate> element is true, the default is 993. User Name <user-name> Specifies the user name for the account to be monitored This element is required when the email application requires authentication. Password <password> Specifies the password that corresponds to the <user-name> provided This element is required when the email application requires authentication. Javamail Debug <javamaildebug> Indicates that debug message logging for JavaMail must be turned on Valid values: true, false (default) Email Address Protocol <emailaddress> <protocol> Specifies the email address of the account to be monitored Specifies the email protocol to be used Valid value: imap Refresh <refresh> Specifies the frequency, in seconds, to check for new messages Default value: 300 seconds (5 minutes) Mail Timeout <mail-timeout> Specifies the time, in seconds, to maintain an established connection. Default value: 60 seconds (1 minute) Connection Timeout <connectiontimeout> Specifies the time, in seconds, to wait when establishing a connection Default value: 30 seconds Disable Auth Login <disable-auth- Prevents the use of non-standard AUTHENTICATE login> LOGIN command with IMAP servers Valid values: true, false (default) No No No No Yes Yes No Conditional Conditional No

480

BMC Atrium Orchestrator Base Adapters User Guide

IMAP mail configuration

Table 161 IMAP mail adapter configuration node elements (part 2 of 5)

UI label Disable Auth Plain Element Description Required No <disable-auth- Prevents the use of AUTHENTICATE PLAIN plain> command with POP servers Valid values: true, false (default) Ignore Attachments <ignoreattachments> Indicates whether attachments must be ignored and excluded from the adapter event Valid values: true, false (default) (attachments permitted) Create Subdirectory <createsubdirectory> Indicates whether each attachment must be downloaded into a separate directory
s

No

No

Subdirectory name format: attachmentdownload-directory/email-address/message ID/timestamp of download in epoch time Sample subdirectory value: /mail/downloads/user@company.com/Message1/ 1196967357

Valid values: true, false (default) (download all the attachments into a single directory) Attachment Download Directory <attachmentdownloaddirectory> Specifies the path and the directory into which attachments on the monitored email messages are downloaded Default value: Tomcat temp directory (on the computer where the CDP is installed) Attachment Overwrite Existing <attachmentoverwriteexisting> Indicates if an attachment with the same file name has No already been downloaded and overwrites that file with the current attachment If the value of the <create-subdirectory> element is true, attachments are downloaded, ignoring the <attachment-overwriteexisting> element. Valid values: true, false (default) (preserves the original file) Attachment Ttl <attachmentttl> Specifies the time an attachment is permitted to reside No in the download directory before being deleted This value is specified as a numeric value followed by a time designator. Valid values for time designators: m - minutes, h hours, d - days Default value: 10d (allows attachments to reside for 10 days) Chapter 5 Mail adapters 481 No

IMAP mail configuration

Table 161 IMAP mail adapter configuration node elements (part 3 of 5)

UI label Max Attachment Size Element <maxattachmentsize> Description Specifies the maximum file size, in MB, which can be attached to a mail message The maximum file size is defined per attachment; the total value of all the files can be greater, provided each file is less than or equal to the default value Default value: 10 MB Max Pool Threads max-poolthreads> Specifies the maximum number of threads to be used No to download attachments in parallel Default value: 1 Delete Attachments On Exit <deleteattachmentson-exit> Deletes all downloaded attachments when the adapter is stopped or disabled Valid values: true, false (default) (preserves downloaded files) Disk Cleanup Interval disk-cleanupinterval> Specifies the interval at which the deletion of attachments that have exceeded the <attachmentttl> period must occur This value is specified as a numeric value followed by a time designator Valid values for time designators: m - minutes, h hours, d - days Default value: 10m (initiates cleanup every 10 minutes) File Name Filter <file-namefilter> Contains the elements that specify the file name criteria for downloading an attachment Only files that satisfy the filter criteria are downloaded. This element is required if the <filename> element is present. File Name <file-name> Specifies the criteria for an attached file to be downloaded, based on the file name You can define one or more file names. A file that matches at least one file name filter is downloaded. If you do not provide a criteria, a file with any file name is downloaded. You can use wildcard characters, * and ? to define the file name filter. With a *, the wild card portion of the file name can contain an unlimited number of characters. With a ?, there is a one-to-one relationship between the ? and the file name character. No Conditional No No Required No

482

BMC Atrium Orchestrator Base Adapters User Guide

IMAP mail configuration

Table 161 IMAP mail adapter configuration node elements (part 4 of 5)

UI label Element Description Required File Type Filter <file-typefilter> Contains the elements that specify the file type criteria Conditional for downloading a file attachment Only files that satisfy the filter criteria are downloaded. This element is required if the <filetype> element is present. File Type <file-type> Specifies the criteria for file download, based on the file type You can define one or more file types. A file that matches at least one file type filter is downloaded. If you do not provide a criteria, a file with any file type is downloaded. Valid values: DOC, XLS, XML, PDF, HTML, EXE Use Ssl Certificate <use-sslcertificate> Specifies whether SSL certificates are used for authentication Valid values: true, false (default) Allow Unsigned Certificates <allowunsignedcertificates> Specifies whether unsigned certificates are permitted for SSL authentication This element is ignored if the value of the <use-sslcertificate> element is false. Valid values: true, false (default) Install Certificate <installcertificate> Updates the default keystore file, java.Home\jre\lib\security\cacerts with the certificates sent by the target URL during the SSLHandshake This element is ignored if the value of the <use-sslcertificate> element is false. If the verification of a certificate fails, the certificate is not installed. To install certificates successfully, the user who installs the peer that executes the request must have read or write access to the keystore file. Certificates are uninstalled when the adapter is disabled on a peer. If a BMC Atrium Orchestrator peer is uninstalled without disabling this adapter, any certificates installed by the adapter continue to exist. The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled. Valid values: true, false (default) No No No No

Chapter 5 Mail adapters

483

IMAP mail configuration

Table 161 IMAP mail adapter configuration node elements (part 5 of 5)

UI label Passphrase Element <passphrase> Description Specifies the passphrase that is used to install certificates for the keystore file This element is ignored if the value of the <use-sslcertificate> element is false. This value must match the passphrase in the keystore. You can change the passphrase using keytool. If you make a change, you must update this value to reflect the new passphrase. Default value: changeit <ignore-peername-inattachment> Set to add or remove peer-name from email event (exists when email contains attachment) XML Valid values: true, false (default) If this element is set to true, <peer-name> element would not be added in email event XML (to avoid deduplication failure). If this element is set to false, <peer-name> element would be added in email event XML (when email contains attachment). No Required No

NOTE
The IMAP mail adapter supports the following message formats for the content of an email:
s s s

Plain text Rich text HTML

484

BMC Atrium Orchestrator Base Adapters User Guide

IMAP mail configuration

Figure 377 shows an XML template of the adapter configuration for the IMAP adapter. Figure 377 XML template of the IMAP adapter configuration
<config> <target></target> <port></port> <user-name></user-name> <password></password> <javamail-debug></javamail-debug> <email-address></email-address> <protocol>imap</protocol> <refresh></refresh> <mail-timeout></mail-timeout> <connection-timeout></connection-timeout> <disable-auth-login></disable-auth-login> <disable-auth-plain></disable-auth-plain> <ignore-attachments></ignore-attachments> <create-subdirectory></create-subdirectory> <attachment-download-directory></attachment-download-directory> <attachment-overwrite-existing></attachment-overwrite-existing> <attachment-ttl></attachment-ttl> <max-attachment-size></max-attachment-size> <max-pool-threads></max-pool-threads> <delete-attachments-on-exit></delete-attachments-on-exit> <disk-cleanup-interval></disk-cleanup-interval> <file-name-filter> <file-name></file-name> </file-name-filter> <file-type-filter> <file-type></file-type> </file-type-filter> <use-ssl-certificate></use-ssl-certificate> <allow-unsigned-certificate></allow-unsigned-certificate> <install-certificate></install-certificate> <passphrase></passphrase> <ignore-peer-name-in-attachment></ignore-peer-name-in-attachment> </config>

Figure 378 shows an XML sample of the IMAP adapter configuration. Figure 378 XML sample of the IMAP adapter configuration
<config> <target>imap.runbox.com</target> <port>993</port> <user-name>testname</user-name> <password>test</password> <javamail-debug>false</javamail-debug> <email-address>test@runbox.com</email-address> <protocol>imap</protocol> <refresh>10</refresh> <mail-timeout/> <connection-timeout>60</connection-timeout> <disable-auth-login>false</disable-auth-login> <disable-auth-plain>false</disable-auth-plain> <delete-after-read>false</delete-after-read> <max-messages-per-connection>20000</max-messages-per-connection> </config>

Figure 379 shows an XML sample of the IMAP adapter configuration with attachment download settings.

Chapter 5 Mail adapters

485

IMAP mail monitor event

Figure 379 XML sample of the IMAP adapter configuration with attachment download settings
<config> <target>imap.runbox.com</target> <user-name>user1</user-name> <password>1234</password> <refresh>20</refresh> <protocol>imap</protocol> <email-address>user1@runbox.com</email-address> <ignore-attachments>false</ignore-attachments> <attachment-download-directory>C:\download_directory</attachment-download-directory> <create-subdirectory>true</create-subdirectory> </config>

Figure 379 shows an XML sample of the IMAP adapter configuration with additional settings. Figure 380 XML sample of the IMAP adapter configuration with additional settings
<config> <target>imap.runbox.com</target> <user-name>user1</user-name> <password>1234</password> <refresh>20</refresh> <protocol>imap</protocol> <email-address>user1@runbox.com</email-address> <javamail-debug>true</javamail-debug> <mail-timeout>60</mail-timeout> <connection-timeout>30</connection-timeout> </config>

IMAP mail monitor event

You can configure an IMAP mail monitor adapter to download or ignore attachments to the email message being monitored. The sample event in Figure 381 on page 487 shows a configuration to display attachments. The sample shows a value for a file that is downloaded, where the <create-subdirectory> element is set to true in the adapter configuration. If an attachment cannot be downloaded, the event includes a <fault-message> element in the <attachment> block, indicating the problem. Each attachment is evaluated independently. You can have a message with multiple attachments, some of which are downloaded successfully, while others produce an error or fault message. Table 162 describes the attachment elements for the IMAP mail adapter. Table 162 IMAP mail adapter event with <attachments> element (part 1 of 2)
Element <email-message> <from> <email-address> <sent-date> Description Contains the values for the email message Contains the email address of the sender Specifies the email address of the account to be monitored Specifies the date the email message is sent

486

BMC Atrium Orchestrator Base Adapters User Guide

IMAP mail monitor event

Table 162 IMAP mail adapter event with <attachments> element (part 2 of 2)
Element <sent-epochmilliseconds> <reply-to> <recipients> <subject> <body> <attachments> <attachment> <peer-name> <download-directory> <name> Description Specifies the date the email message is sent, in epoch time format This value can be used to perform a date comparison in a rule. Specifies the addresses to which a reply to the email message is directed Contains the email address of the recipients Specifies the subject line of the email message Specifies the body of the email message Contains the information about attachments to the email message Contains the information about an attachment to the email message Specifies the name of the peer on which the attachment is downloaded Specifies the directory in which the attachment is downloaded Specifies the file name of the attachment that is downloaded

Figure 381 shows the XML sample of the IMAP adapter event with an attachment that is successfully downloaded. Figure 381 XML sample of the IMAP adapter event with an attachment successfully downloaded
<email-message> <from> <email-address>email</email-address> </from> <sent-date>date</sent-date> <sent-epoch-milliseconds>date in epoch time</sent-epoch-milliseconds> <reply-to> <email-address>email</email-address> <email-address>email</email-address> </reply-to> <recipients> <email-address>email</email-address> <email-address>email</email-address> </recipients> <subject>subject text</subject> <body>body text</body> <attachments> <attachment> <peer-name>CDP</peer-name> <download-directory>/mail/downloads/user@company.com/Message1/1196967357</downloaddirectory> <name>Test1.doc</name> </attachment> <attachment> <peer-name>CDP</peer-name> <download-directory>/mail/downloads/user@company.com/Message2/1196968330</downloaddirectory> <name>Test2.doc</name> </attachment> </attachments> </email-message>

To use the data from the monitor adapter event in the triggered process, a Job Input Parameter, inputevent must be created on the Start activity of the process. The <data> element from the monitor adapter event automatically populates this input.
Chapter 5 Mail adapters 487

IMAP mail monitor event

Table 163 describes the adapter event elements for the IMAP mail adapter with an attachment that cannot be downloaded. Table 163 IMAP mail adapter event with an attachment having elements that cannot be downloaded
Element <email-message> <from> <sent-date> <sent-epochmilliseconds> <reply-to> <recipients> <subject> <body> <attachments> <attachment> <fault-message> <name> Description Contains the values for the email message Contains the email address of the sender Specifies the date the email message is sent Specifies the date the email message is sent, in epoch time format This value can be used to perform a date comparison in a rule. Specifies the addresses to which a reply to the email message is directed Contains the lines for the email address of the recipients Specifies the subject line of the email message Specifies the body of the email message Contains the information about attachments to the email message Contains the information about an attachment to the email message Indicates the reason the attachment could not be downloaded successfully Specifies the file name of the attachment that could not be downloaded

Figure 382 shows an XML sample of the adapter event for the IMAP adapter with an attachment that cannot be downloaded.

488

BMC Atrium Orchestrator Base Adapters User Guide

POP mail adapter

Figure 382 XML sample of the IMAP mail adapter event with an attachment that cannot be downloaded
<email-message> <from> <email-address>email</email-address> </from> <sent-date>date</sent-date> <sent-epoch-milliseconds>date in epoch time</sent-epoch-milliseconds> <reply-to> <email-address>email</email-address> <email-address>email</email-address> </reply-to> <recipients> <email-address>email</email-address> <email-address>email</email-address> </recipients> <subject>subject text</subject> <body>body text</body> <attachments> <attachment> <fault-message> Attachment could not be downloaded attachment name violates filter set</fault-message> <name>Sample1.doc</name> </attachment> <attachment> <fault-message> Attachment could not be downloaded as it exceeds maximum attachment size limit </fault-message> <name>Sample2.doc</name> </attachment> </attachments> </email-message>

POP mail adapter

The Post Office Protocol (POP) mail adapter checks for messages in a specified account on a POP3 mail server. The account information is designated in the configuration node for the adapter in Grid Manager. This adapter does not support multiple configuration nodes, but you can configure multiple POP mail adapters can within Grid Manager, each with a unique configuration node and adapter name. This section describes the following configuration and event formats of the POP mail adapter:

POP mail adapter configuration

POP mail event

POP mail adapter configuration

The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after enabling the adapter.

Chapter 5 Mail adapters

489

POP mail adapter configuration

BMC recommends that you do not include unused elements in the adapter configuration because they might cause errors. Adapter type: ro-adapter-pop[version] See Configuring the adapter on page 14 to configure the POP mail adapter. Table 164 describes the adapter configuration elements for the POP mail adapter that you can specify by 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. Table 164 POP mail adapter configuration node elements (part 1 of 6)
UI label Target Port Element <target> <port> Description Required Specifies the host name or the IP address of the POP3 Yes server Specifies the port on which the POP3 server listens If the value of the <use-ssl-certificate> element is false, the default value is 110. If the value of the <use-ssl-certificate> element is true, the default value is 995. User Name Password Javamail Debug <user-name> <password> <javamaildebug> Specifies the user name for the account to be monitored Specifies the password that corresponds to the <user-name> provided Indicates that debug message logging for JavaMail must be turned on Valid values: true, false (default) Email Address <emailaddress> Specifies the email address of the account to be monitored BMC recommends that you do not configure multiple POP mail monitor adapters to monitor the same email-address. Protocol <protocol> Specifies the email protocol to be used Valid value: pop3 Refresh <refresh> Specifies the frequency, in seconds, to check for new messages Default value: 300 seconds (5 minutes) Mail Timeout <mailtimeout> Specifies the time, in seconds, to maintain an established connection Default value: 60 seconds (1 minute) No No Yes Yes Yes Yes No No

490

BMC Atrium Orchestrator Base Adapters User Guide

POP mail adapter configuration

Table 164 POP mail adapter configuration node elements (part 2 of 6)

UI label Connection Timeout Element Description Required No <connection- Specifies the time, in seconds, to wait when timeout> establishing a connection Default value: 30 seconds Disable Auth Login <disableauth-login> Prevents the use of non-standard AUTHENTICATE LOGIN command with POP servers Valid values: true, false (default) Disable Auth Plain <disableauth-plain> Prevents the use of AUTHENTICATE PLAIN command with POP servers Valid values: true, false (default) Delete After Read <deleteafter-read> Determines whether a message must be deleted from the server after it is read by the adapter. This element is necessary to use the <maxmessages-per-connection> element. Do not use this element if you configure multiple POP mail monitor adapters to monitor the same email address. Exceptions are generated in the grid.log file and messages might be deleted before all the adapters read the message. Valid values: true, false (default) Max Messages <maxPer Connection messagesperconnection> Specifies the maximum number of messages to be pulled per connection attempt If there are more messages on the server than the number specified, they are retrieved during the next polling. This element is used only when the value of the <delete-after-read> element is true. Default value: 20 Ignore Attachments <ignoreIndicates whether attachments must be ignored and attachments> excluded from the adapter event Valid values: true, false Default value: false (attachments permitted) No No Conditional No No

Chapter 5 Mail adapters

491

POP mail adapter configuration

Table 164 POP mail adapter configuration node elements (part 3 of 6)

UI label Create Subdirectory Element Description Required No <createIndicates whether each attachment must be subdirectory downloaded into a separate directory > s Subdirectory name format: attachmentdownload-directory/<email-address>/message ID/timestamp of download in epoch time
s

Sample subdirectory value: /mail/downloads/user@company.com/ Message1/1196967357

Valid values: true, false Default value: false (download all the attachments into a single directory) Attachment Download Directory <attachment- Specifies the path and the directory into which downloadattachments on the monitored email messages are directory> downloaded This directory must exist on each peer on which the adapter is enabled. If this directory is absent, the configuration is considered invalid and the adapter is not enabled. Default value: Java temp directory Attachment Overwrite Existing <attachment- Indicates if an attachment with the same file name has No overwritealready been downloaded and overwrites that file with the current attachment existing> If the value of the <create-subdirectory> element is true, attachments are downloaded, ignoring the <attachment-overwriteexisting> element. Valid values: true, false Default value: false (preserves the original file) Attachment Ttl <attachment- Specifies the time an attachment is permitted to reside No ttl> in the download directory before being deleted This value is specified as a numeric value followed by a time designator. Valid values for time designators: m - minutes, h hours, d - days Default value: 10d (allows attachments to reside for 10 days) No

492

BMC Atrium Orchestrator Base Adapters User Guide

POP mail adapter configuration

Table 164 POP mail adapter configuration node elements (part 4 of 6)

UI label Max Attachment Size Element <maxattachmentsize> Description Specifies the maximum file size, in MB, which can be attached to a mail message The maximum file size is defined per attachment; the total value of all the files can be greater, provided each file is less than or equal to the default value. Default value: 10 MB Max Pool Threads <max-poolthreads> Specifies the maximum number of threads to be used No to download attachments in parallel Default value: 1 Delete Attachments On Exit <deleteDeletes all downloaded attachments when the attachments- adapter is stopped or disabled on-exit> Valid values: true, false Default value: false (preserves downloaded files) <diskcleanupinterval> Specifies the interval at which the deletion of attachments that have exceeded the <attachmentttl> period must occur This value is specified as a numeric value followed by a time designator. Valid values for time designators: m - minutes, h hours, d - days Default value: 10m (initiates cleanup every 10 minutes) File Name Filter <file-namefilter> Contains the elements that specify the file name criteria for a file download You can download only those files that satisfy the filter criteria. This element is required if the <filename> element is present. File Name <file-name> Specifies the criteria for an attached file to be downloaded, based on the file name You can define one or more file names. An attachment that matches at least one file name filter is downloaded. If you do not provide a criteria, a file with any file name is downloaded. You can use wildcard characters, * and ? to define the file name filter. With a *, the wild card portion of the file name can contain an unlimited number of characters. With a ?, there is a one-to-one relationship between the ? and the file name character. No Conditional No Required No

Disk Cleanup Interval

No

Chapter 5 Mail adapters

493

POP mail adapter configuration

Table 164 POP mail adapter configuration node elements (part 5 of 6)

UI label Element Description Required File Type Filter <file-typefilter> Contains the elements that specify the file type criteria Conditional for downloading a file attachment You can download only those files that satisfy the filter criteria. This element is required if the <filetype> element is present. File Type <file-type> Specifies the criteria for an attached file to be downloaded, based on the file type You can define one or more file types. A file that matches at least one file type filter is downloaded. If you do not provide a criteria, a file with any file type is downloaded. Valid values: DOC, XLS, XML, PDF, HTML, EXE Use Ssl Certificate <use-sslSpecifies whether SSL certificates are used for certificate> authentication. Valid values: true, false Default value: false Allow Unsigned Certificates Specifies whether unsigned certificates are permitted No <allowfor SSL authentication unsignedcertificates This element is ignored if the value of the <use-ssl> certificate> value is false. Valid values: true, false (default) No No

494

BMC Atrium Orchestrator Base Adapters User Guide

POP mail adapter configuration

Table 164 POP mail adapter configuration node elements (part 6 of 6)

UI label Install Certificate Element Description Required No <installUpdates the default keystore file, certificate> java.Home\jre\lib\security\cacerts with the certificates sent by the target URL during the SSLHandshake This element is ignored if the value of the <use-sslcertificate> element is false. If the verification of a certificate fails, the certificate is not installed. To install certificates successfully, the user who installs the peer that executes the request must have read or write access to the keystore file. Certificates are uninstalled when the adapter is disabled on a peer. If a BMC Atrium Orchestrator peer is uninstalled without disabling this adapter, any certificates installed by the adapter continue to exist. The validity of installed certificates is checked once every 24 hours. The first check is conducted 24 hours after the adapter is enabled. Valid values: true, false (default) Passphrase <passphrase> Specifies the passphrase that is used to install certificates for the keystore file This element is ignored if the value of the <use-sslcertificate> element is false This value must match the passphrase in the keystore. You can change the passphrase using keytool. If you make a change, you must update this value to reflect the new passphrase Default value: changeit No

NOTE
The POP mail adapter supports the following message formats for the content of an email:
s s s

Plain text Rich text HTML

Chapter 5 Mail adapters

495

POP mail adapter configuration

Figure 383 shows an XML template of the adapter configuration for the POP mail adapter. Figure 383 XML template of the POP adapter configuration
<config> <target></target> <port></port> <user-name></user-name> <password></password> <javamail-debug></javamail-debug> <email-address></email-address> <protocol>pop3</protocol> <refresh></refresh> <mail-timeout></mail-timeout> <connection-timeout></connection-timeout> <disable-auth-login></disable-auth-login> <disable-auth-plain></disable-auth-plain> <delete-after-read></delete-after-read> <max-messages-per-connection></max-messages-per-connection> <create-subdirectory></create-subdirectory> <ignore-attachments></ignore-attachments> <attachment-download-directory></attachment-download-directory> <attachment-overwrite-existing></attachment-overwrite-existing> <attachment-ttl></attachment-ttl> <max-attachment-size></max-attachment-size> <max-pool-threads></max-pool-threads> <delete-attachments-on-exit></delete-attachments-on-exit> <disk-cleanup-interval></disk-cleanup-interval> <file-name-filter> <file-name></file-name> </file-name-filter> <file-type-filter> <file-type></file-type> </file-type-filter> <use-ssl-certificate></use-ssl-certificate> <allow-unsigned-certificate></allow-unsigned-certificate> <install-certificate></install-certificate> <passphrase></passphrase> </config>

Figure 384 shows an XML sample of the POP mail adapter configuration. Figure 384 XML sample of the POP mail adapter configuration
<config> <target>pop.gawab.com</target> <port>110</port> <user-name>testname</user-name> <password>aa</password> <javamail-debug>false</javamail-debug> <email-address>aa@gawab.com</email-address> <protocol>pop3</protocol> <refresh>10</refresh> <mail-timeout/> <connection-timeout>60</connection-timeout> <disable-auth-login>false</disable-auth-login> <disable-auth-plain>false</disable-auth-plain> <delete-after-read>false</delete-after-read> <max-messages-per-connection>20000</max-messages-per-connection> </config>

496

BMC Atrium Orchestrator Base Adapters User Guide

POP mail event

Figure 385 shows an XML sample of the POP mail adapter configuration with additional settings. Figure 385 XML sample of the POP mail adapter configuration with additional settings
<config> <target>pop.runbox.com</target> <user-name>user1</user-name> <password>1234</password> <refresh>20</refresh> <protocol>pop3</protocol> <email-address>user1@runbox.com</email-address> <javamail-debug>true</javamail-debug> <mail-timeout>60</mail-timeout> <connection-timeout>30</connection-timeout> </config>

Figure 386 shows an XML sample of the POP mail adapter configuration with attachment download settings. Figure 386 XML sample of the POP mail adapter configuration with attachment download settings
<config> <target>pop.runbox.com</target> <user-name>user1</user-name> <password>1234</password> <refresh>20</refresh> <protocol>pop3</protocol> <email-address>user1@runbox.com</email-address> <ignore-attachments>false</ignore-attachments> <attachment-download-directory>${CDPMachineTempDir}</attachment-download-directory> <max-attachment-size>1</max-attachment-size> </config>

POP mail event

You can configure a POP mail monitor adapter to download or ignore attachments to the email message being monitored. Depending on this configuration, the <attachments> block shown in the sample event in Figure 387 might not be present. If an attachment cannot be downloaded, due to configuration settings or available disk space, the event includes a <fault-message> element in the <attachment> block, indicating the problem. Table 165 describes the adapter elements for the POP mail adapter with attachments downloaded successfully. Table 165 POP mail with attachments successfully downloaded adapter elements (part 1 of 2)
Element <email-message> <from> <sent-date> Description Contains the values for the email message Contains the email address of the sender Specifies the date the email message is sent

Chapter 5 Mail adapters

497

POP mail event

Table 165 POP mail with attachments successfully downloaded adapter elements (part 2 of 2)
Element <sent-epochmilliseconds> <reply-to> <recipients> subject> <body> <attachments> <attachment> <peer-name> <name> Description Specifies the date the email message is sent, in epoch time format This value can be used to perform a date comparison in a rule. Specifies the addresses to which a reply to the email message is directed Contains the email address of the recipients Specifies the subject line of the email message Specifies the body of the email message Contains the information about attachments to the email message Contains the information about an attachment to the email message Specifies the name of the peer on which the attachment is downloaded Specifies the file name of the attachment that is downloaded

<download-directory> Specifies the directory into which the attachment is downloaded

Figure 387 shows a sample event with an attachment that could not be downloaded. The sample shows a value for a file that is downloaded, where the value of the <create-subdirectory> element is set to true in the adapter configuration. Each attachment is evaluated independently. You can have a message with multiple attachments, some of which are downloaded successfully, while others produce a fault message. Figure 387 XML sample of the POP adapter event with attachments that are successfully downloaded
<email-message> <from> <email-address>email</email-address> </from> <sent-date>date</sent-date> <sent-epoch-milliseconds>date in epoch time</sent-epoch-milliseconds> <reply-to> <email-address>email</email-address> <email-address>email</email-address> </reply-to> <recipients> <email-address>email</email-address> <email-address>email</email-address> </recipients> <subject>subject text</subject> <body>body text</body> <attachments> <attachment> <peer-name>CDP</peer-name> <download-directory>/mail/downloads/user@company.com/Message1/1196967357/downloaddirectory> <name>Test1.doc</name> </attachment> <attachment> <peer-name>CDP</peer-name> <download-directory>/mail/downloads/user@company.com/Message2/1196968330</downloaddirectory> <name>Test2.doc</name> </attachment> </attachments> </email-message>

498

BMC Atrium Orchestrator Base Adapters User Guide

POP mail event

To use the data from the monitor adapter event in the triggered process, a Job Input Parameter, inputevent, must be created on the Start Activity of the process. The <data> element from the monitor adapter event automatically populates this input. Table 166 describes the adapter event elements for the POP mail adapter with attachments that cannot be downloaded successfully. Table 166 POP mail adapter event with attachments that cannot be downloaded elements
Element <email-message> <from> <sent-date> <sent-epochmilliseconds> <reply-to> <recipients> <subject> <body> <attachments> <attachment> <fault-message> <name> Description Contains the values for the email message Contains the email address of the sender Specifies the date the email message is sent Specifies the date the email message is sent, in epoch time format This value can be used to perform a date comparison in a rule. Specifies the addresses to which a reply to the email message is directed Contains the email address of the recipients Specifies the subject line of the email message Specifies the body of the email message Contains the information about attachments to the email message Contains the information about an attachment to the email message Indicates the reason the attachment could not be downloaded successfully Specifies the file name of the attachment that could not be downloaded

Figure 388 shows an XML sample of the adapter event for the POP adapter with attachments that cannot be downloaded successfully.

Chapter 5 Mail adapters

499

POP mail event

Figure 388 XML sample of the POP adapter event with attachments that cannot be downloaded
<email-message> <from> <email-address>email</email-address> </from> <sent-date>date</sent-date> <sent-epoch-milliseconds>date in epoch time</sent-epoch-milliseconds> <reply-to> <email-address>email</email-address> <email-address>email</email-address> </reply-to> <recipients> <email-address>email</email-address> <email-address>email</email-address> </recipients> <subject>subject text</subject> <body>body text</body> <attachments> <attachment> <fault-message> Attachment could not be downloaded attachment name violates filter set</fault-message> <name>Sample1.doc</name> </attachment> <attachment> <fault-message> Attachment could not be downloaded as it exceeds maximum attachment size limit </fault-message> <name>Sample2.doc</name> </attachment> </attachments> </email-message>

500

BMC Atrium Orchestrator Base Adapters User Guide

Chapter

6
503 504 504 505 505 505 505 507 510 511 513 514 515 516 519 519 520 521 523 525 526 528 531 533 534 535 536 537 538 539 540 541 543 544
501

Adapter utilities module

This chapter presents the following topics: Overview of the OA Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoke SOAP request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email SMTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ad Hoc Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ad Hoc Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameterized Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminal File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminal FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cdup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6 Adapter utilities module

ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 put. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 rm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Terminal SCP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Terminal SFTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 chgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 chown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 get-dir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 lcd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 lpwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 mkdirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 put dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 put. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 rm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 symlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Terminal Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Terminal SSH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Terminal Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Terminal Kerberos ticket properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Terminal Kerberos SSH1 adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 Terminal Kerberos SSH1 adapter configuration with valid TGT specified . . . . 609 Terminal Kerberos SSH1 adapter configuration with dynamic targets. . . . . . . . 610 Terminal Kerberos SSH2 adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Terminal Kerberos SSH2 adapter configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Terminal Kerberos SSH2 adapter configuration with krb-realm . . . . . . . . . . . . . 614 Terminal Kerberos SSH2 adapter configuration elements. . . . . . . . . . . . . . . . . . . 614 Terminal Kerberos SSH2 adapter configuration with dynamic targets. . . . . . . . 615 Terminal Kerberos SSH2 adapter configuration elements with dynamic targets . . 617 Terminal Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Terminal Windows Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Make SOAP requestmethod one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Make SOAP requestmethod two . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

502

BMC Atrium Orchestrator Base Adapters User Guide

Overview of the OA Module

Overview of the OA Module

The AD Operations Actions Module is automatically installed when you install BMC Atrium Orchestrator. You can use the processes contained in this module to simplify the configuration of base adapters. This module provides easy-to-use processes, referred to as adapter wrappers, for each of the actions supported by a base adapter. These adapter wrappers are used to create an XML document that an adapter requires to execute an adapter request. The password field in the Autopilot-ADUtilities wrappers now supports encrypted password using secure data-type in the configuration item. Any resulting adapter response is returned for use in subsequent activities in the workflow.

Before you begin 1 Import and unbundle the AutoPilot-OA-Common-Utilities module. 2 Activate the module on the grid in which the adapter wrappers are used.
For details about this supporting module, see the BMC Atrium Orchestrator Development Studio Online Help. The AutoPilot Utilities Module is automatically installed when the first Configuration Distribution peer (CDP) is installed. This module is copied into the Grid Library for each grid created in Grid Manager. The following sections outline the steps required to import a module from the Grid Library, import a module from an external source, unbundle a module, activate a snapshot, and activate individual modules. Modules are installed from the Library on a specific grid. You can import modules directly from the Grid Library directory, which resides on a CDP or from an external source, such as a CD or hard disk. The BMC Atrium Orchestrator platform includes an adapter Utilities Module called AutoPilot Utilities (file name AutoPilot-AD-Utilities) which contains processes that streamline the use of base adapters in workflows. These processes are referred to as adapter wrappers. Each process uses input parameters to create the adapter request and then produces one or more output parameters containing the adapter response. To use an adapter wrapper in an existing workflow process, drag the desired adapter wrapper on to the process canvas. This creates a Call Process activity for the adapter wrapper. To configure the Call Process activity, values must be assigned to each Call Process input parameter that is designated as required. Default values are automatically assigned for many optional inputs. If these default values are acceptable, no further assignments are necessary. Output parameters are available as indicated in the following sections. These output parameters can be mapped to Context Items for use in subsequent activities.

Chapter 6 Adapter utilities module

503

Common

For details on assigning input and output parameter values, see the Call Process activity section of the BMC Atrium Orchestrator Development Studio User Guide. The following sections provide information about each adapter wrapper, including the expected Input and output parameters.

Common
This process directory is used to hold the core processes used by the workflows in the AutoPilot Utilities Module. Any changes to these processes might have far-reaching implications because many workflows use these processes. BMC recommends that you make a copy of these processes and modify the copy if you need to make changes.

Invoke SOAP request

This process is used when generating a process from a Web Services Definition Language (WSDL), using the WSDL to Workflow Process Generation Wizard. Do not use this process outside the wizard function.

Tokenize String
The Tokenize String process segments a string on a specified delimiter. Table 167 describes the process input parameters for the Invoke SOAP request process. Table 167 Process inputsTokenize String
Process input string delimiter Description Specifies the string to be parsed Specifies the character on which the specified string is parsed Default value: None Required Yes No

Table 168 describes the process output parameters for the Invoke SOAP request process. Table 168 Process outputsTokenize String
Process output tokens Description Specifies an XML document with a root element, <tokens>, and child elements, <token>, containing the resulting string segments

504

BMC Atrium Orchestrator Base Adapters User Guide

Email SMTP

Email SMTP
The SMTP adapter contains the send email process.

Send Email
The Send Email process sends an email message to one or more recipients using the SMTP protocol. There are no defined outputs for this process. Table 169 describes the process input parameters for the SMTP adapter with send mail process. Table 169 Process inputssend email
Process input <adapter name> <to address list> <from address> <cc address list> Description Specifies the name of the adapter to use for this process Default value: SMTPAdapter Specifies the comma separated list of email addresses This populates the To address line of the email message. Specifies the comma separated list of email addresses This populates the From address line of the email message. Specifies the comma separated list of email addresses This populates the CC address line of the email message. Default: Blank CC list <subject> <body> Specifies the subject line for the email message Specifies the body of the email message Default: Empty body Yes No No Yes Yes Required No

HTTP
Get
The Get process gets HTML content using a URL.

Chapter 6 Adapter utilities module

505

Get

Table 170 describes the process input parameters for the HTTP adapter with the Get process. Table 170 Process inputsGet (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: HTTPAdapter url Specifies the URL defining the location of the content to be obtained Default value: None data-format Specifies the format of the data Valid values: HTML_DATA_FORMAT, XML_DATA_FORMAT Default value: HTML_DATA_FORMAT use-sslcertificate Specifies whether to establish a secure connection Valid values: true, false Default value: false allowunsignedcertificate Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false Default value: false installcertificate Specifies whether to install certificates Valid values: true, false Default value: false passphrase Specifies the Java Standard Trust Key Store passphrase Default value: changeit user name Specifies the user name to be used for basic authentication No No No No No Yes Yes Required No

506

BMC Atrium Orchestrator Base Adapters User Guide

Post

Table 170 Process inputsGet (part 2 of 2)

Process input password connection properties Description Specifies the password corresponding to the user name provided for basic authentication Includes an XML document for the http connection properties to specify the user name and password for basic authentication and to set the information in the HTTP request header before executing the http request Note: user name and password properties are not set in request Header and properties are case sensitive. For example: <http-connection-properties> <Content-Type>text/html</Content-Type> <Accept>Yes</Accept> <Blob></Blob> </http-connection-properties> Required No

Table 171 describes the process output parameters for the HTTP adapter with the Get process. Table 171
status code status reason header lines message body

Process outputsGet
Description Specifies the HTTP status code Specifies the HTTP status reason Specifies the HTTP header lines Specifies the message body

Process outputs

Post
The Post process sends data to a specified URL.

Chapter 6 Adapter utilities module

507

Post

Table 172 describes the process input parameters for the HTTP adapter with the Post process. Table 172 Process inputsPost (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: HTTPAdapter url Specifies the URL defining the location of the content to be sent Default value: None data-format Specifies the format of the data Valid values: HTML_DATA_FORMAT, XML_DATA_FORMAT Default value: HTML_DATA_FORMAT data Specifies the information to be posted This information can be simple text or it can use an XML document to specify parent and child or key and value tags. For example, Simple Text: Sample data that will be posted. XML Format: Parent - Child Format:
<parent> <child>child value</child> </parent>

Required No

Yes

Yes

Yes

Kay - Value Format:

<entry> <key>key</key> <value>value</value> </entry>

use-sslcertificate

Specifies whether to establish a secure connection Valid values: true, false Default value: false

No

508

BMC Atrium Orchestrator Base Adapters User Guide

Post

Table 172 Process inputsPost (part 2 of 2)

Process input allowunsignedcertificate Description Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false Default value: false installcertificate Specifies whether to install certificates Valid values: true, false Default value: false passphrase Specifies the Java Standard Trust Key Store passphrase Default value: changeit user name password connection properties Specifies the user name to be used for basic authentication Specifies the password corresponding to the user name provided for basic authentication No No No No Required No

Includes an XML document for the http connection properties to specify the No user name and password for basic authentication and to set the information in the HTTP request header before executing the http request Note: user name and password properties are not set in request Header and properties are case sensitive. For example: <http-connection-properties> <Content-Type>text/html</Content-Type> <Accept>Yes</Accept> <Blob></Blob> </http-connection-properties>

Table 173 describes the process output parameters for the HTTP adapter with the Post process. Table 173 Process outputsPost
Process outputs status code status reason header lines message body Description Specifies the HTTP status code Specifies the HTTP status reason Specifies the HTTP header lines Specifies the message body

Chapter 6 Adapter utilities module

509

Put

Put
The Put process, like the Post process sends data to a specified URL. Also, the Put process can send a data file to the URL. Table 174 describes the process input parameters for the HTTP adapter with the Put process. Table 174 Process inputsPut (part 1 of 2)
Description Specifies the name of the adapter to use for this process Default value: HTTPAdapter url Specifies the URL defining the location of the content to be sent Default value: None data-format Specifies the format of the data Valid values: HTML_DATA_FORMAT, XML_DATA_FORMAT Default value: HTML_DATA_FORMAT use-sslcertificate Specifies whether to establish a secure connection Valid values: true, false Default value: false allowunsignedcertificate Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false Default value: false installcertificate Specifies whether to install certificates Valid values: true, false Default value: false passphrase Specifies the Java Standard Trust Key Store passphrase Default value: changeit user name password data Specifies the user name to be used for basic authentication Specifies the password corresponding to the user name provided for basic authentication Specifies the information to be sent No No No No No No No Yes Yes Required No

Process input adapter name

510

BMC Atrium Orchestrator Base Adapters User Guide

Delete

Table 174
file path

Process inputsPut (part 2 of 2)

Description Required Specifies the local path of the file (including the file name) to be sent over the No URL For example, Windows: C:\\adapters\\testfile.txt UNIX/Solaris: //home//user//testfile.txt

Process input

connection properties

Includes an XML document for the http connection properties to specify the No user name and password for basic authentication and to set the information in the HTTP request header before executing the http request Note: user name and password properties are not set in request Header and properties are case sensitive. For example: <http-connection-properties> <Content-Type>text/html</Content-Type> <Accept>Yes</Accept> <Blob></Blob> </http-connection-properties>

Table 175 describes the process output parameters for the HTTP adapter with the Put process. Table 175 Process outputsPut
Process outputs status code status reason header lines message body Description Specifies the HTTP status code Specifies the HTTP status reason Specifies the HTTP header lines Specifies the message body

Delete
The Delete process requests the server to delete the resource identified by the request URL.

Chapter 6 Adapter utilities module

511

Delete

Table 176 describes the process input parameters for the HTTP adapter with the Delete process. Table 176 Process inputsDelete (part 1 of 2)
Description Specifies the name of the adapter to use for this process Default value: HTTPAdapter url Specifies the URL defining the location of the content to be deleted Default value: None html-syntaxcorrection data-format Specifies whether to ignore the parsing and send the HTML body as a sting No Default value: true Specifies the format of the data Valid values: HTML_DATA_FORMAT, XML_DATA_FORMAT Default value: HTML_DATA_FORMAT use-sslcertificate Specifies whether to establish a secure connection Valid values: true, false Default value: false allowunsignedcertificate Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false Default value: false installcertificate Specifies whether to install certificates Valid values: true, false Default value: false passphrase Specifies the Java Standard Trust Key Store passphrase Default value: changeit user name Specifies the user name to be used for basic authentication No No No No No Yes Yes Required No

Process input adapter name

512

BMC Atrium Orchestrator Base Adapters User Guide

JMS

Table 176
password connection properties

Process inputsDelete (part 2 of 2)

Description Specifies the password corresponding to the user name provided for basic authentication Required No

Process input

Includes an XML document for the http connection properties to specify the No user name and password for basic authentication and to set the information in the HTTP request header before executing the http request Note: user name and password properties are not set in request Header and properties are case sensitive. For example: <http-connection-properties> <Content-Type>text/html</Content-Type> <Accept>Yes</Accept> <Blob></Blob> </http-connection-properties>

Table 177 describes the process output parameters for the HTTP adapter with the Delete process. Table 177 Process outputsDelete
Process outputs status code status reason header lines message body Description Specifies the HTTP status code Specifies the HTTP status reason Specifies the HTTP header lines Specifies the message body

JMS
The JMS adapter contains the following processes:
s

Send Body Send Messages

Chapter 6 Adapter utilities module

513

Send Body

Send Body
The Send Body process sends a set of JMS messages to a designated JMS destination. Table 178 describes the process input parameters for the JMS adapter with the send body process. Table 178 Process inputssend body
Process adapter name Description Specifies the name of the adapter to use for this process Default value: JMSAdapter destination body Specifies the destination queue Specifies the body of the message to be sent This must be in XML format with a root element, <body>, and one or more child elements, <message>, containing the content to be sent. headers Specifies the header of the message to be sent This must be in XML format with a root element, <header>, and only one of the following child elements:
s s s s s s

Required No

Yes Yes

No

reply-to expiration correlation-id jms-type priority delivery-mode No

properties

Contains the properties list for the message This must be in XML format with a root element, <properties>, and one or more child elements, <property>, containing the content to be sent.

requestSpecifies the time, in milliseconds, the actor adapter waits for a reply to No response-wait- a message timeout If the reply is received before the timeout duration, the adapter sends the next message. Otherwise, it waits for the timeout duration, and then sends the next message. The adapters synchronous request or response behavior depends on this tag. If this tag is present in the adapter request, the adapter sends messages synchronously.

514

BMC Atrium Orchestrator Base Adapters User Guide

Send Messages

Table 179 describes the process output parameters for the JMS adapter with the Send Body process. Table 179 Process outputsSend Body
Process outputs adapter response Description Contains the result returned from the adapter request The contents of the response vary with the adapter.

Send Messages
The Send Messages process sends a set of JMS messages to a designated JMS destination. Table 180 describes the process input parameters for the JMS adapter with the Send Messages process. Table 180 Process inputsSend Messages (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: JMSadapter destination text messages Specifies the JMS destination queue for the messages Specifies the text messages to be sent This must be in XML format with a root element, <messages>, and one or more child elements, <text>, containing the content to be sent. map messages Specifies the map messages to be sent This must be in XML format with a root element, <messages>, and one or more child elements, <map>, containing the key value elements. bytes messages Specifies the bytes messages to be sent This must be in XML format with a root element, <messages>, and one or more child elements, <bytes>, containing the bytes content to be sent. reply to correlation id jms priority Specifies the JMS destination for sending a reply Specifies the JMSCorrelationID header property Specifies the JMSPriority header property Valid values: Between 0 to 9 jms type Specifies the JMSType header property No No No No No Conditional Conditional Yes Conditional Required No

jms expiration Specifies the JMSExpiration header property value is in milliseconds

Chapter 6 Adapter utilities module

515

PowerShell

Table 180 Process inputsSend Messages (part 2 of 2)

Process input Description Required No delivery mode Specifies the JMS DeliveryMode header property Valid values: PERSISTENT, NON_PERSISTENT properties Contains the properties list for the messages This must be in XML format with a root element, <properties> and one or more child elements, <property>, containing the content to be sent. requestSpecifies the time, in milliseconds, the actor adapter waits for a reply to No response-wait- a message timeout If the reply is received before the timeout duration, the adapter sends the next message. Otherwise, it waits for the timeout duration, and then sends the next message. The adapters synchronous request or response behavior depends on this tag. If this tag is present in adapter request, the adapter sends messages synchronously. No

Table 181 describes the process output parameters for the JMS adapter with the Send Messages process. Table 181 Process outputsSend Messages
Process outputs adapter response Description Contains the result returned from the adapter request The contents of the response vary with the adapter.

PowerShell
The PowerShell adapter process is a part of AutoPilot AD-Utility module and is bundled under the terminal folder of the AD-Utility module. To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set, you cannot retrieve partial information from the configuration node. In this sample, the target is a dynamic target. You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

516

BMC Atrium Orchestrator Base Adapters User Guide

PowerShell

Figure 389 shows a sample adapter request for the get-service PowerShell command. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio. Figure 389 XML sample of the PowerShell adapter request for the get-service command
<powershell-request> <targets> <target> <host>computer2</host> <user-name>testuser</user-name> <password>testpass</password> <powershell-version>1.0</powershell-version> <powershell-consolefile>pshell.psc1</powershell-consolefile> <use-userprofile>true</use-userprofile> </target> </targets> <commands> <command>get-service</command> </commands> </powershell-request>

Table 182 describes the elements for this request. Table 182 PowerShell adapter request elements
Input element <targets> <target> Description Contains the <target> elements Specifies a target to be referenced in the request If the target element is not defined, the default target in the adapter configuration is used. <host> Contains the host name or the IP address of the remote or local computer This element is required when defining a dynamic target. <user-name> Contains the user name to be used for authentication on the remote host This element is required when defining a dynamic target. <password> Contains the password corresponding to the specified user name for authentication on the remote host This element is required when defining a dynamic target. <powershellversion> <powershellconsolefile> <use-userprofile> Specifies the version of PowerShell on which the command is to be executed Valid value: 1.0 Specifies the PowerShell console file to be loaded Specifies whether the user profile is to be loaded Valid values: true, false <commands> <command> Contains a single or multiple command elements Contains the PowerShell command to be executed

Chapter 6 Adapter utilities module

517

PowerShell

Table 183 describes the process input parameters for the PowerShell adapter. Table 183 PowerShell adapter inputs
Input element adapter name Description Specifies the name of the adapter to be used for this process Default name: MicrosoftPowerShell target command command encryption type command timeout host name Specifies the fully-qualified host name or IP address of the remote or the local computer Specifies the PowerShell command to be executed, including arguments Specifies the method of encryption used for the specified command value Valid values: Base64, Plain Specifies the time, in seconds, allotted to complete the execution of the command Contains the host name or the IP address of the remote or local computer If this element is absent, the target details from the adapter configuration are used. user name password Contains the user name to be used for authentication on the remote host Contains the password corresponding to the specified user name for authentication on the remote host

password encryption type Specifies the method of encryption used for the password provided Valid values: Base64, Plain version Specifies the version of PowerShell on which the command is to be executed Valid value: 1.0 use user profile Specifies whether the user profile is to be loaded Valid values: true, false console file Specifies the PowerShell console file to be loaded

Table 184 describes the process output parameters for the PowerShell adapter. Table 184 PowerShell adapter outputs
Output Element <adapter response> Description Contains the result returned from the adapter request The contents of the response vary depending on the adapter.

518

BMC Atrium Orchestrator Base Adapters User Guide

SNMP

SNMP
The SNMP adapter contains the Get process.

Get
The Get process gets the values of one or more OIDs from a remote SNMP agent. Table 185 describes the process input parameters for the SNMP adapter with get process. Table 185 Process inputsGet (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SNMPAdapter host port Specifies the host name or the IP address of the remote host Specifies the port on which that the remote SNMP agent is running Default value: 161 community version Specifies the SNMP community string used to access the remote SNMP Yes agent Specifies the SNMP protocol version to be used Valid values: 1, 2c Default value: 1 retries Specifies the number of times the remote SNMP agent must be contacted if the agent does not respond Default value: 3 timeout Specifies the amount of time, in seconds, to receive a response Default value: 5 seconds oid value 0 oid value 1 Specifies the first OID to obtain Specifies the first optional OID to obtain If you do not specify a value for this input, this optional OID is not obtained. oid value 2 Specifies the second optional OID to obtain No Yes No No No No Yes No Required No

Chapter 6 Adapter utilities module

519

SQL

Table 185 Process inputsGet (part 2 of 2)

Process input oid value 3 Description Specifies the third optional OID to obtain If you do not specify a value for this input, this OID is not obtained. oid value 4 Specifies the fourth optional OID to obtain If you do not specify a value for this input, this OID is not obtained. No Required No

Table 186 describes the process output parameters for the SNMP adapter with get process. Table 186 Process outputsGet
Process output response 0 response 1 response 2 response 3 response 4 Description Specifies the value associated with the first OID requested Specifies the value associated with the first optional OID requested Specifies the value associated with the second optional OID requested Specifies the value associated with the third optional OID requested Specifies the value associated with the fourth optional OID requested

SQL
The SQL adapter contains the following processes:
s

Ad Hoc Query Ad Hoc Update Delete Insert Update Select

520

BMC Atrium Orchestrator Base Adapters User Guide

Ad Hoc Query

Ad Hoc Query
The Ad Hoc Query process executes an ad hoc query against an SQL database. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements. Table 187 describes the process input parameters for the SQL adapter with the Ad Hoc Query process. Table 187 Process inputsAd Hoc Query (part 1 of 2)
Process Input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter sql target host port user name password subprotocol Specifies the SQL query statement to be executed Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver. url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No Yes No No No No No No Required No

max Specifies the maximum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis max active connections initial active connections

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running Specifies the maximum number of connections allowed in the connection pool Specifies the minimum number of connections created during adapter startup No No

Chapter 6 Adapter utilities module

521

Ad Hoc Query

Table 187 Process inputsAd Hoc Query (part 2 of 2)

Process Input max idle connections min idle connections Description Specifies the maximum number of allowed idle connections allowed at any time Required No

Specifies the minimum number of idle connections allowed at any time No No

validate query Specifies the query statement used to validate the connection

validate Indicates whether a connection is validated when returned to the pool No connections on return With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target No No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

Table 188 describes the process output parameters for the SQL adapter with the Ad Hoc Query process. Table 188 Process outputsAd Hoc Query
Process Outputs adapter response Description Specifies the SQL actor adapter response

522

BMC Atrium Orchestrator Base Adapters User Guide

Ad Hoc Update

Ad Hoc Update
The AD Hoc Update process executes an ad hoc update against an SQL database. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements. Table 189 describes the process input parameters for the SQL adapter with the Ad Hoc Update process. Table 189 Process inputsAd Hoc Update (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter sql target host port user name password subprotocol Specifies the SQL update statement to execute Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No Yes No No No No No No Required No

max Specifies the maximum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis max active connections initial active connections

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running Specifies the maximum number of connections allowed in the connection pool Specifies the minimum number of connections created during adapter startup No No

Chapter 6 Adapter utilities module

523

Ad Hoc Update

Table 189 Process inputsAd Hoc Update (part 2 of 2)

Process input max idle connections min idle connections Description Required Specifies the maximum number of idle connections allowed at any time No Specifies the minimum number of idle connections allowed at any time No No

validate query Specifies the query statement used to validate the connection

No validate Specifies whether a connection is validated when returned to the pool connections on return With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target No No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

Table 190 describes the process output parameters for the SQL adapter with the Ad Hoc Update process. Table 190 Process outputsAd Hoc Update
Process output adapter response Description Contains the SQL actor adapters response

524

BMC Atrium Orchestrator Base Adapters User Guide

Delete

Delete
The Delete process deletes rows from an SQL database. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements. Table 191 describes the process input parameters for the SQL adapter with the Delete process. Table 191 Process inputsDelete (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdpater table where Specifies the name of the table from which rows are deleted Specifies the conditional SQL expression used to define rows to be deleted If you do not specify a value for this input, all the rows in the specified table are deleted target host port user name password subprotocol database driver Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No No No No No No No Yes No Required No

max Specifies the maximum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running

Chapter 6 Adapter utilities module

525

Insert

Table 191 Process inputsDelete (part 2 of 2)

Process input max active connections min idle connections Description Specifies the maximum number of connections allowed in the connection pool Required No

Specifies the minimum number of idle connections allowed at any time No No

validate query Specifies the query statement used to validate the connection

validate Indicates whether a connection is validated when returned to the pool No connections on return With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target No No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

There are no defined outputs for this process.

Insert
The Insert process inserts rows into a designated table in an SQL database. If an SQL exception occurs while attempting to perform the operation (owing to a failure to provide a required column, a mismatch between the columns and value parameters being detected, or some other issue), the Compensation process executes. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements.

526

BMC Atrium Orchestrator Base Adapters User Guide

Insert

Table 192 describes the process input parameters for the SQL adapter with the Insert process. Table 192 Process inputsInsert (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter table columns values Specifies the name of the table into which rows are inserted Specifies the comma separated list of column names for which values are provided Specifies the comma separated list of the values to be used to form the new row, where each value is associated with the column name specified in the columns input parameter, in the same position in the list Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No Yes Yes Yes Required No

target host port user name password subprotocol

No No No No No No

max Specifies the maximum time, in milliseconds, that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis max active connections initial active connections

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running Specifies the maximum number of connections allowed in the connection pool Specifies the minimum number of connections created during adapter startup No No

Chapter 6 Adapter utilities module

527

Select

Table 192 Process inputsInsert (part 2 of 2)

Process input max idle connections min idle connections Description Specifies the maximum number of allowed idle connections Required No

Specifies the minimum number of idle connections allowed at any time No No

validate query Specifies the query statement used to validate the connection

validate Indicates whether a connection is validated when returned to the pool No connections on return With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target No No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

There are no defined outputs for this process.

Select
The Select process issues a select statement against an SQL database, retrieving a set of rows. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements.

528

BMC Atrium Orchestrator Base Adapters User Guide

Select

Table 193 describes the process input parameters for the SQL adapter with the Select process. Table 193 Process inputsSelect (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter where Specifies the conditional expression that determines which rows are returned For a join operation, the expression must include equality relationships for the primary and foreign keys in the tables being joined. If you do not specify a value for this input, all the rows are returned from a single table. Do not include the where command in the expression; it is supplied by the process. The process creates a statement combining the where, where operator, and where value inputs as follows: WHERE <where> <where operator> <where value> where value Determines which rows are returned This element is used with the <where> input. If you do not specify a value for this input, all the rows are returned from a single table. where operator Determines which rows are returned This element is used with the <where> input. If you do not specify a value for this input, all the rows are returned from a single table. Valid values: =, <>,!=, <, >, <=, >=, !<, !> group by Specifies the expression (using a column number or column name) that No causes the output to be grouped by a particular column If you do not specify a value for this input, no grouping is performed. If included, one or more of the columns selected must include an SQL aggregation function. Valid values: SUM(), COUNT() order by Specifies the expression (using a column number or column name) that No causes the output to be ordered by a particular column If you do not specify a value for this input, no ordering is performed. The expression can include a space followed by ASC or DESC to sort in the ascending or the descending order. table name Specifies the table name, or, for a join operation, a comma separated list Yes of table names No No No Required No

Chapter 6 Adapter utilities module

529

Select

Table 193 Process inputsSelect (part 2 of 3)

Process input columns Description Required Specifies the comma separated list of column names from which values No are obtained If you do not specify a value for this input, all the values are returned for all the columns. Optionally, a column name can be enclosed by an SQL aggregation function. Valid values: SUM(), COUNT() target host port user name password subprotocol Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No No No No No No No

max Specifies the maximum time, in milliseconds that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis max active connections initial active connections max idle connections min idle connections

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running Specifies the maximum number of connections allowed in the connection pool Specifies the minimum number of connections created during adapter startup No No

Specifies the maximum number of idle connections allowed at any time No Specifies the minimum number of idle connections allowed at any time No No

validate query Specifies the query statement used to validate the connection

530

BMC Atrium Orchestrator Base Adapters User Guide

Update

Table 193 Process inputsSelect (part 3 of 3)

Process input Description Required No validate Indicates whether periodic checks are done on idle connections in the connections on pool. return With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool. With a value of true, the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target No No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

Table 194 describes the process output parameters for the SQL adapter with the Select process. Table 194 Process outputsSelect
Process output adapter response Description Specifies the SQL actor adapters response

Update
The Update process issues an update statement against an SQL database. This process handles any necessary CDATA wrapping for SQL statements. The inputs must contain plain SQL statements.

Chapter 6 Adapter utilities module

531

Update

Table 195 describes the process input parameters for the SQL adapter with the Update process. Table 195 Process inputsUpdate (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter table column value where Specifies the table to update Specifies the column to update Specifies the value to place in the updated column Specifies the conditional expression used to determine the rows to be updated If you do not specify a value for this input, all the rows are updated. Do not include the where command in the expression; it is supplied by the process. target host port user name password subprotocol Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value. database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver url max wait Specifies the complete connection URL for the target database Specifies the maximum time, in milliseconds, to wait before timing out while establishing a connection to a database No No No No No No No No No No No Yes Yes Yes No Required No

max Specifies the maximum time, in milliseconds that a connection can connection remain idle before being evaluated for termination idle time millis min Specifies the minimum time, in milliseconds that a connection can connection remain idle before being evaluated for termination idle time millis evictor idle time millis max active connections

No

Specifies the frequency, in milliseconds, at which a thread closes an idle No connection that is running Specifies the maximum number of connections allowed in the connection pool No

532

BMC Atrium Orchestrator Base Adapters User Guide

Parameterized Statements

Table 195 Process inputsUpdate (part 2 of 2)

Process input initial active connections max idle connections min idle connections Description Specifies the minimum number of connections created during adapter startup Required No

Specifies the maximum number of idle connections allowed at any time No Specifies the minimum number of idle connections allowed at any time No No No

validate query Specifies the query statement used to validate the connection validate Indicates whether a connection is validated when returned to the pool connections on return With a value of true the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. validate idle connections Indicates whether periodic checks are done on idle connections in the pool With a value of true the connection is evaluated to determine the status and, if not alive, the connection is removed from the pool. connection name Specifies the reference name of a connection to the specified target

No

No No

ktgt-cache-file Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) to obtain a connection through the Kerberos tunnel

Note: For the Windows OS, the path should be a fully qualified path using double slashes (\\) instead of a single slash (\) to the krb ticket file. For example, C:\\testFolder\\ticketFile <ktgt-cache-file>/tmp/krb5cc_0</ktgt-cachefile> krb-serviceprincipal Specifies the name of the service principal registered with the Sybase database to allow Kerberos authentication This element is required if the <ktgt-cache-file> element is used. For example, <krb-serviceprincipal>REALOPSLINUX1@SYNAPSE.COM</krb-serviceprincipal> Conditional

There are no defined outputs for this process.

Parameterized Statements
The Parameterized Statements process executes multiple parameterized SQL statements.

Chapter 6 Adapter utilities module

533

Terminal File

Table 196 describes the process input parameters for the Parameterized statements process. Table 196 Process inputsDelete
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SQLAdapter target host port user name password subprotocol Identifies the target defined in the SQL actor adapter configuration in Grid Manager Specifies the host name or the IP address of the database server Specifies the port on which the database server listens Specifies the user name used for database authentication Specifies the password that corresponds to the user name provided Specifies the driver-specified subprotocol used to build a connection The adapter prepends to the provided value database driver Specifies the name of the database to which the adapter connects Specifies the fully qualified JDBC driver classname Valid values: com.sybase.jdbc3.jdbc.SybDriver, oracle.jdbc.driver.OracleDriver statements Contains details of SQL statements It must contain one or more statement elements in XML format with a root element, <statements>, and one or more child elements, <statement>, containing the query to be executed. enable transaction Specifies whether to use a transaction for all the statements Valid values are: true, false Default value: false No Yes No No No No No No No No Required No

Terminal File
The Terminal File adapter contains the following processes:
s

Append Delete read Write

534

BMC Atrium Orchestrator Base Adapters User Guide

Append

Append
The Append process appends up to nine lines to a specified text file. Table 197 describes the process input parameters for the File adapter with the Append process. Table 197 Process inputsAppend (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FileAdapter file name line 1 Specifies the name of the file to which lines are appended Specifies the first line to be appended If you do not specify a value for this input, nothing is appended. line 2 Specifies the second line to be appended If you do not specify a value for this input, nothing is appended. line 3 Specifies the third line to be appended If you do not specify a value for this input, nothing is appended. line 4 Specifies the fourth line to be appended If you do not specify a value for this input, nothing is appended. line 5 Specifies the fifth line to be appended If you do not specify a value for this input, nothing is appended. line 6 Specifies the sixth line to be appended If you do not specify a value for this input, nothing is appended. line 7 Specifies the seventh line to be appended If you do not specify a value for this input, nothing is appended. line 8 Specifies the eighth line to be appended If you do not specify a value for this input, nothing is appended. No No No No No No No Yes No Required No

Chapter 6 Adapter utilities module

535

Delete

Table 197 Process inputsAppend (part 2 of 2)

Process input line 9 Description Specifies the ninth line to be appended If you do not specify a value for this input, nothing is appended. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required No

Table 198 describes the process output parameters for the File adapter with the Append process. Table 198 Process outputsAppend
Process adapter response Description Specifies the File adapters response

Delete
The Delete process deletes a specified file. Table 199 describes the process input parameters for the File adapter with the Delete process. Table 199 Process inputsDelete
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: FileAdapter file name Specifies the absolute path and the file name of the file to be deleted Yes Required No

Table 200 describes the process output parameters for the File adapter with the Delete process. Table 200 Process outputsDelete
Process output adapter response Description Specifies the File adapters response

536

BMC Atrium Orchestrator Base Adapters User Guide

Read

Read
The Read process reads from a designated file and provides tokenization for text files. Table 201 describes the process input parameters for the File adapter with the Read process. Table 201 Process inputsRead
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FileAdapter file name file type Specifies the name of the file to be read Specifies the type of file to be read Valid values: TEXT, XML Default value: TEXT delimiter Specifies the character used to mark the separation of fields on a line This input is required for tokenization. You must precede special characters with a \ to prevent XML parsing errors. header Determines whether the first line in the file is treated as a header This input is required for tokenization. Valid values: true, false character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Conditional Yes No Required No

Table 202 lists the sample delimiter formats. Table 202 Sample delimiter formats (part 1 of 2)
Delimiter tab pipe asterisk dash comma Format \t \| \* \, OR \,

Chapter 6 Adapter utilities module

537

Write

Table 202 Sample delimiter formats (part 2 of 2)

Delimiter semi colon underscore dollar sign Format ; OR \; _ OR \_ \$

Table 203 describes the process output parameters for the File adapter with the Read process. Table 203 Process outputsRead
Process output adapter response Description Specifies the File adapters response The format varies based on the inputs provided.

Write
The Write process writes an XML document or up to nine text lines to a specified file. Table 204 describes the process input parameters for the File adapter with the Write process. Table 204 Process inputsWrite (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FileAdapter file name file type Specifies the name of the file to which lines are written Specifies the type of file to which lines are written Valid values: XML, TEXT line 1 Specifies the first line to write If you do not provide a value, nothing is written. line 2 Specifies the second line to write If you do not provide a value, nothing is written. line 3 Specifies the third line to write If you do not provide a value, nothing is written. No No No Yes Yes Required No

538

BMC Atrium Orchestrator Base Adapters User Guide

Terminal FTP

Table 204 Process inputsWrite (part 2 of 2)

Process input line 4 Description Specifies the fourth line to write If you do not provide a value, nothing is written. line 5 Specifies the fifth line to write If you do not provide a value, nothing is written. line 6 Specifies the sixth line to write If you do not provide a value, nothing is written. line 7 Specifies the seventh line to write If you do not provide a value, nothing is written. line 8 Specifies the eighth line to write If you do not provide a value, nothing is written. line 9 Specifies the ninth line to write If you do not provide a value, nothing is written. xml doc Specifies an XML document to be written This input is used with an XML file type. If you do not specify a value for this input, nothing is written. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No No No No No No No Required No

Table 205 describes the process output parameters for the File adapter with the Write process. Table 205 Process outputsWrite
Process output adapter response Description Specifies the File adapters response

Terminal FTP
The FTP adapter is used to transfer files and perform specific commands on a remote target using the FTP protocol. A process is available for each command.

Chapter 6 Adapter utilities module

539

Append

Append
The Append process appends the contents of a local file to an existing remote file. Table 206 describes the process input parameters for the FTP adapter with the Append process. Table 206 Process inputsAppend (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target configured in the FTP adapter (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local file remote file host name Specifies the file to be appended to a specified remote file Specifies the remote file to which the local file is appended Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds with the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Yes Yes Conditional No Required No

540

BMC Atrium Orchestrator Base Adapters User Guide

cd

Table 206 Process inputsAppend (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target and is required if a dynamic target is used. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 207 describes the process output parameters for the FTP adapter with the Append process. Table 207 Process outputsAppend
Process output adapter response Description Specifies the FTP adapters response

cd
The cd process changes the working directory on the remote server.

Chapter 6 Adapter utilities module

541

cd

Table 208 describes the process input parameters for the FTP adapter with the cd process. Table 208 Process inputscd
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target configured in the FTP adapter (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. directory host name Indicates the directory the remote host must use as the working directory Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name password Specifies the user name to be used for remote host authentication Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Conditional Conditional Conditional Yes Conditional No Required No

542

BMC Atrium Orchestrator Base Adapters User Guide

cdup

Table 209 describes the process output parameters for the FTP adapter with the cd process. Table 209 Process outputs -cd
Process output adapter response Description Specifies the FTP adapters response

cdup
The cdup process changes the working directory on the remote server to a directory one level above the current working directory. Table 210 describes the process input parameters for the FTP adapter with the cdup process. Table 210 Process inputs -cdup (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

543

get

Table 210 Process inputs -cdup (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 211 describes the process output parameters for the FTP adapter with the cdup process. Table 211 Process outputscdup
Description Specifies the FTP adapters response

Process output adapter response

get
The get process obtains a file from the remote server and places it on the local server.

544

BMC Atrium Orchestrator Base Adapters User Guide

get

Table 212 describes the process input parameters for the FTP adapter with the get process. Table 212 Process inputsget (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local file Specifies the local path, including the file name This is the destination file for the get command If you do not specify a value for this input, the path provided for the remote file is used. This path must correspond to a valid path on the local server. remote file Specifies the remote path, including the file name This is the source file for the get command. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds with the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional Yes No No Required No

Chapter 6 Adapter utilities module

545

ls

Table 212 Process inputsget (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 213 describes the process output parameters for the FTP adapter with the get process. Table 213 Process outputsget
Process output adapter response Description Specifies the FTP adapters response

ls
The ls process lists the files in the specified directory on the remote server.

546

BMC Atrium Orchestrator Base Adapters User Guide

ls

Table 214 describes the process input parameters for the FTP adapter with the ls process. Table 214 Process inputsls (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. directory Indicates the directory on the remote host for which files must be listed No If you do not specify a value for this input, files are listed for the working directory. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

547

mkdir

Table 214 Process inputsls (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 215 describes the process output parameters for the FTP adapter with the ls process. Table 215 Process outputsls
Process output adapter response Description Specifies the FTP adapters response

mkdir
The mkdir process creates a directory in an existing path on the remote server.

548

BMC Atrium Orchestrator Base Adapters User Guide

mkdir

Table 216 describes the process input parameters for the FTP adapter with the mkdir process. Table 216 Process inputsmkdir (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActoradapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. directory host name Indicates the existing path on the remote server and the name of the directory to be created Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Yes Conditional No Required No

Chapter 6 Adapter utilities module

549

mode

Table 216 Process inputsmkdir (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 217 describes the process output parameters for the FTP adapter with the mkdir process. Table 217 Process outputsmkdir
Description Specifies the FTP adapters response

Process output adapter response

mode
The mode process sets the transfer mode to either ASCII or binary.

550

BMC Atrium Orchestrator Base Adapters User Guide

mode

Table 218 describes the process input parameters for the FTP adapter with the mode process. Table 218 Process inputsmode (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. transfer mode Indicates the transfer mode Valid values: binary, ascii host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional Yes No Required No

Chapter 6 Adapter utilities module

551

put

Table 218 Process inputsmode (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 219 describes the process input parameters for the FTP adapter with the mode process. Table 219 Process outputsmode
Process output adapter response Description Specifies the FTP adapters response

put
The put process transfers a file from the local server to the remote server.

552

BMC Atrium Orchestrator Base Adapters User Guide

put

Table 220 describes the process input parameters for the FTP adapter with the put process. Table 220 Process inputsput (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local file Specifies the local path, including the file name This is the source file for the put command remote file Specifies the remote path, including the file name This is the destination file for the put command If you do not specify a value for this input, the path provided for the local file is used. This path must correspond to a valid path on the remote server. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Yes No Required No

Chapter 6 Adapter utilities module

553

pwd

Table 220 Process inputsput (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 221 describes the process output parameters for the FTP adapter with the put process. Table 221 Process outputsput
Process output adapter response Description Specifies the FTP adapters response

pwd
The pwd process prints the working directory on the remote server.

554

BMC Atrium Orchestrator Base Adapters User Guide

pwd

Table 222 describes the process input parameters for the FTP adapter with the pwd process. Table 222 Process inputspwd
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

555

rename

Table 223 describes the process output parameters for the FTP adapter with the pwd process. Table 223 Process outputspwd
Process output adapter response Description Specifies the FTP adapters response

rename
The rename process changes the name of the specified file on the remote server. Table 224 describes the process input parameters for the FTP adapter with the rename process. Table 224 Process inputsrename (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. old file new file host name Specifies the remote path, including the file name of the existing file to be renamed Specifies the remote path, including the new file name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Yes Yes Conditional No Required No

556

BMC Atrium Orchestrator Base Adapters User Guide

rm

Table 224 Process inputsrename (part 2 of 2)

Process input password Description Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Required Conditional

Table 225 describes the process output parameters for the FTP adapter with the rename process. Table 225 Process outputsrename
Process outputs adapter response Description Specifies the FTP adapters response

rm
The rm process deletes a file from the remote server. Table 226 describes the process input parameters for the FTP adapter with the rm process.

Chapter 6 Adapter utilities module

557

rm

Table 226 Process inputsrm

Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. path and filename host name Specifies the remote path, including the file name This file is removed from the remote server. Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Conditional Conditional Conditional Conditional Yes No Required No

558

BMC Atrium Orchestrator Base Adapters User Guide

rmdir

Table 227 describes the process output parameters for the FTP adapter with the rm process. Table 227 Process outputsrm
Process outputs adapter response Description Specifies the FTP adapters response

rmdir
The rmdir process deletes a directory from the remote server. Table 228 describes the process input parameters for the FTP adapter with the rmdir process. Table 228 Process inputsrmdir (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. directory Specifies the remote path, including the directory This directory is removed from the remote server host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional Yes No Required No

Chapter 6 Adapter utilities module

559

stat

Table 228 Process inputsrmdir (part 2 of 2)

Process inputs Description password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Required Conditional

Table 229 describes the process output parameters for the FTP adapter with the rmdir process. Table 229 Process outputsrmdir
Process outputs adapter response Description Specifies the FTP adapters response

stat
The stat process obtains the status of a file or a directory on the remote server. Table 230 describes the process input parameters for the FTP adapter with the stat process.

560

BMC Atrium Orchestrator Base Adapters User Guide

stat

Table 230 Process inputsstat

Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: FTPActorAdapter target Identifies the target defined in the FTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. file name Specifies the remote path, including the file name or the directory The status for this file or the directory is returned. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No Conditional Conditional Conditional Conditional Conditional Yes No Required No

Chapter 6 Adapter utilities module

561

Terminal SCP

Table 231 describes the process output parameters for the FTP adapter with the stat process. Table 231 Process outputsstat
Process outputs adapter response Description Specifies the FTP adapters response

Terminal SCP
The terminal SCP contains the following processes:
s

Get Put

Get
The Get process transfers a file to a peer running an SCP adapter from a remote SCP host. Table 232 describes the process input parameters for the SCP adapter with the Get process. Table 232 Process inputsGet (part 1 of 3)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SCPAdapter target Identifies the target defined in the SCP actor adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local file Specifies the local path, including the file name This is the destination file for the get action. remote file Specifies the remote path, including the file name This is the source file for the get action. Yes Yes No Required No

562

BMC Atrium Orchestrator Base Adapters User Guide

Get

Table 232 Process inputsGet (part 2 of 3)

Process inputs Description host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target and is required if a dynamic target is used. user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. Conditional Conditional Conditional Conditional Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

563

Put

Table 232 Process inputsGet (part 3 of 3)

Process inputs Description preferred pk algorithm Required Specifies the preference of the algorithm used to encrypt the public key Conditional Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds

Table 233 describes the process output parameters for the SCP adapter with the Get process. Table 233 Process outputsGet
Process outputs adapter response Description Specifies the SCP adapters response

Put
The Put process transfers a file from a peer running an SCP adapter to a remote SCP host. Table 234 describes the process input parameters for the SCP adapter with the Put process. Table 234 Process inputsPut (part 1 of 3)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SCPAdapter target Identifies the target defined in the SCP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local file Specifies the local path, including the file name This is the source for the put action. remote file Specifies the remote path, including the file name This is the destination for the put action. Yes Yes No Required No

564

BMC Atrium Orchestrator Base Adapters User Guide

Put

Table 234 Process inputsPut (part 2 of 3)

Process inputs Description host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target and is required if a dynamic target is used. user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir /.ssh /known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. Conditional Conditional Conditional Conditional Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

565

Terminal SFTP

Table 234 Process inputsPut (part 3 of 3)

Process inputs Description preferred pk algorithm Required Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target default value: 60 seconds

Table 235 describes the process output parameters for the SCP adapter with the Put process. Table 235 Process outputsPut
Process outputs adapter response Description Specifies the SCP adapters response

Terminal SFTP
The SFTP adapter is used to transfer files and perform specific commands on a remote target using the SFTP protocol.

cd
The cd process changes the working directory on the remote server. Table 236 describes the process input parameters for the SFTP adapter with the cd process.

566

BMC Atrium Orchestrator Base Adapters User Guide

cd

Table 236 Process inputscd (part 1 of 2)

Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts Conditional Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

567

chgrp

Table 236 Process inputscd (part 2 of 2)

Process inputs Description allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa directory character-set Indicates the directory the remote host must use as the working directory Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No Required Conditional

Table 237 describes the process output parameters for the SFTP adapter with the cd process. Table 237 Process outputscd
Process outputs adapter response Description Specifies the SFTP adapters response

chgrp
The chgrp process changes the group for a specified file.

568

BMC Atrium Orchestrator Base Adapters User Guide

chgrp

Table 238 describes the process input parameters for the SFTP adapter with the chgrp process. Table 238 Process inputschgrp (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target and is required if a dynamic target is used. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts Conditional Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

569

chgrp

Table 238 Process inputschgrp (part 2 of 2)

Process inputs Description allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa group id file name Specifies the group ID that is assigned to the specified file (path) Specifies the remote file path, including the file name The group on this file is changed. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Yes Yes Required Conditional

Table 239 describes the process output parameters for the SFTP adapter with the chgrp process. Table 239 Process outputschgrp
Process outputs adapter response Description Specifies the SFTP adapters response

570

BMC Atrium Orchestrator Base Adapters User Guide

chmod

chmod
The chmod process changes the permissions for a specified file. Table 240 describes the process input parameters for the SFTP adapter with the chmod process. Table 240 Process inputschmod (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

571

chmod

Table 240 Process inputschmod (part 2 of 2)

Process inputs Description known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa file name Specifies the remote path, including the file name The permissions on this file are changed. permissions character-set Specifies the permissions that are assigned to the specified file Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No Yes Conditional Required Conditional

572

BMC Atrium Orchestrator Base Adapters User Guide

chown

Table 241 describes the process output parameters for the SFTP adapter with the chmod process. Table 241 Process outputschmod
Process output adapter response Description Specifies the SFTP adapters response

chown
The chown process changes the owner of a specified file. Table 242 describes the process input parameters for the SFTP adapter with the chown process. Table 242 Process inputschown (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

573

chown

Table 242 Process inputschown (part 2 of 3)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa file name Specifies the remote path, including the file name The owner of this file is changed. user id Specifies the user ID that is assigned to the specified file Yes Yes Conditional Conditional Required Conditional

574

BMC Atrium Orchestrator Base Adapters User Guide

get-dir

Table 242 Process inputschown (part 3 of 3)

Process input character-set Description Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Required No

Table 243 describes the process output parameters for the SFTP adapter with the chown process. Table 243 Process outputschown
Process outputs adapter response Description Specifies the SFTP adapters response

get-dir
The get-dir process retrieves the contents of a specified directory from a remote server and places it on the local server. Table 244 describes the process input parameters for the SFTP adapter with the getdir process. Table 244 Process inputsget-dir (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. No Required No

Chapter 6 Adapter utilities module

575

get-dir

Table 244 Process inputsget-dir (part 2 of 3)

Process input Description Required No local directory Specifies the local path, including the directory This is the destination directory for the get-dir command. If you do not specify a value for this input, the path provided for the remote file is used. This path must correspond to a valid path on the local server. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts Conditional Conditional Conditional Conditional Conditional Conditional

576

BMC Atrium Orchestrator Base Adapters User Guide

get-dir

Table 244 Process inputsget-dir (part 3 of 3)

Process input allow unknown hosts Description Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa remote directory character-set Specifies the remote path, including the directory This is the source directory for the get-dir command. Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Yes Required Conditional

Table 245 describes the process output parameters for the SFTP adapter with the getdir process. Table 245 Process outputsget-dir
Process output adapter response Description Specifies the SFTP adapters response

Chapter 6 Adapter utilities module

577

get

get
The get process retrieves a file from a remote location and places it on the local system. Table 246 describes the process input parameters for the SFTP adapter with the get process. Table 246 Process inputsget (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. Conditional Conditional Conditional Conditional Conditional No Required No

578

BMC Atrium Orchestrator Base Adapters User Guide

get

Table 246 Process inputsget (part 2 of 2)

Process input known hosts config Description Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa local file Specifies the local path, including the file name This is the destination for the get command. If you do not specify a value for this input, the path provided for the remote file is used. This path must correspond to a valid path on the local server. remote file Specifies the remote path, including the file name This is the source for the get command. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Yes No Conditional Required Conditional

Table 247 describes the process output parameters for the SFTP adapter with the get process.

Chapter 6 Adapter utilities module

579

lcd

Table 247 Process outputsget

Process outputs adapter response Description Specifies the SFTP adapters response

lcd
The lcd process changes the working directory on the local server. Table 248 describes the process input parameters for the SFTP adapter with the lcd process. Table 248 Process inputsIcd (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

580

BMC Atrium Orchestrator Base Adapters User Guide

lcd

Table 248 Process inputsIcd (part 2 of 2)

Process inputs Description password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa directory character-set Indicates the directory the local host must use as the working directory Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

581

lpwd

Table 249 describes the process output parameters for the SFTP adapter with the lcd process. Table 249 Process outputsIcd
Process outputs adapter response Description Specifies the SFTP adapters response

lpwd
The lpwd process retrieves the working directory on the local server. Table 250 describes the process input parameters for the SFTP adapter with the lpwd process. Table 250 Process inputslpwd (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

582

BMC Atrium Orchestrator Base Adapters User Guide

lpwd

Table 250 Process inputslpwd (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

583

ls

Table 251 on page 584 describes the process output parameters for the SFTP adapter with the lpwd process. Table 251 Process outputslpwd
Process output adapter response Description Specifies the SFTP adapters response

ls
The ls process lists the files on the remote server. Table 252 describes the process input parameters for the SFTP adapter with the ls process. Table 252 Process inputsls (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

584

BMC Atrium Orchestrator Base Adapters User Guide

ls

Table 252 Process inputsls (part 2 of 2)

Process inputs Description password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa directory character-set Indicates the directory on the remote server for which files are listed Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

585

mkdir

Table 253 on page 586 describes the process output parameters for the SFTP adapter with the ls process. Table 253 Process outputsls
Process outputs adapter response Description Specifies the SFTP adapters response

mkdir
The mkdir process creates a directory in an existing directory path on a remote server. Table 254 describes the process input parameters for the SFTP adapter with the mkdir process. Table 254 Process inputsmkdir (part 1 of 2)
Process adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional conditional No Required No

586

BMC Atrium Orchestrator Base Adapters User Guide

mkdir

Table 254 Process inputsmkdir (part 2 of 2)

Process password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa directory character-set Indicates the existing path on the remote server and the name of the directory to be created Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

587

mkdirs

Table 255 describes the process output parameters for the SFTP adapter with the mkdir process. Table 255 Process outputsmkdir
Process outputs adapter response Description Specifies the SFTP adapters response

mkdirs
The mkdirs process creates a directory and any directories in the path that do not currently exist on a remote server. Table 256 describes the process input parameters for the SFTP adapter with the mkdirs process. Table 256 Process inputsmkdirs (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

588

BMC Atrium Orchestrator Base Adapters User Guide

mkdirs

Table 256 Process inputsmkdirs (part 2 of 2)

Process input password encryption type Description Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa directory Indicates the remote path and the directory to be created Any supporting directories that do not currently exist are created. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Yes Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

589

put dir

Table 257 describes the process output parameters for the SFTP adapter with the mkdirs process. Table 257 Process outputsmkdirs
Process output adapter response Description Specifies the SFTP adapters response

put dir
The put dir process retrieves the contents of a specified directory from a remote server and places it on the local server. Table 258 describes the process input parameters for the SFTP adapter with the put dir process. Table 258 Process inputsput dir (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. local directory Specifies the local path, including the directory This is the source for the put dir command. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Yes No Required No

590

BMC Atrium Orchestrator Base Adapters User Guide

put dir

Table 258 Process inputsput dir (part 2 of 3)

Process input password Description Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/ known_host allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa remote directory Specifies the remote path, including the directory This is the destination for the put-dir command. This path must correspond to a valid path on the remote server. If you do not specify a value for this input, the path provided for the local file is used. No Conditional Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

591

put

Table 258 Process inputsput dir (part 3 of 3)

Process input character-set Description Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Required No

Table 259 describes the process output parameters for the SFTP adapter with the put dir process. Table 259 Process outputsput dir
Process output adapter response Description Specifies the SFTP adapters response.

put
The put process retrieves a file from a local system and places it in a remote location. Table 260 describes the process input parameters for the SFTP adapter with the put process. Table 260 Process inputsput (part 1 of 3)
Process Input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. Conditional No Required No

592

BMC Atrium Orchestrator Base Adapters User Guide

put

Table 260 Process inputsput (part 2 of 3)

Process Input port Description Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa Conditional Conditional Conditional Conditional Conditional Required Conditional

Chapter 6 Adapter utilities module

593

pwd

Table 260 Process inputsput (part 3 of 3)

Process Input local file Description Specifies the local path, including the file name This is the source file for the put command. establishconnectiontimeout-secs remote file Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Specifies the remote path, including the file name This is the destination file for the put command. If you do not specify a value for this input, the path provided for the local file is used. This path must correspond to a valid path on the remote server. character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No No Required Yes

Table 261 describes the process output parameters for the SFTP adapter with the put process. Table 261 Process outputsput
Process output adapter response Description Specifies the SFTP adapters response

pwd
The pwd process retrieves the working directory on the remote server. Table 262 describes the process input parameters for the SFTP adapter with the pwd process.

594

BMC Atrium Orchestrator Base Adapters User Guide

pwd

Table 262 Process inputspwd (part 1 of 2)

Process Input adapter name target Description Specifies the name of the adapter to use for this process Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Valid values: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts Conditional Conditional Conditional Conditional Conditional Conditional Required No No

Chapter 6 Adapter utilities module

595

rename

Table 262 Process inputspwd (part 2 of 2)

Process Input allow unknown hosts Description Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa character-set Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Required Conditional

Table 263 describes the process output parameters for the SFTP adapter with the pwd process. Table 263 Process outputs -pwd
Process output adapter response Description Specifies the SFTP adapters response

rename
The rename process changes the group for a specified file. Table 264 describes the process input parameters for the SFTP adapter with the rename process.

596

BMC Atrium Orchestrator Base Adapters User Guide

rename

Table 264 Process inputsrename (part 1 of 2)

Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts Conditional Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

597

rename

Table 264 Process inputsrename (part 2 of 2)

Process input allow unknown hosts Description Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa old file Specifies the remote path, including the file name of the existing file This file is renamed. new file character-set Specifies the remote path, including the new file name Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Yes No No Required Conditional

Table 265 describes the process output parameters for the SFTP adapter with the rename process. Table 265 Process outputsrename
Process output adapter response Description Specifies the SFTP adapters response

598

BMC Atrium Orchestrator Base Adapters User Guide

rm

rm
The rm process deletes a specified file from the remote server. Table 266 describes the process input parameters for the SFTP adapter with the rm process. Table 266 Process inputsrm (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. Conditional Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

599

rm

Table 266 Process inputsrm (part 2 of 2)

Process input known hosts config Description Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_host allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa file name character-set Indicates the remote path, including the directory or the file name to be Yes removed Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds No Conditional Required Conditional

Table 268 describes the process output parameters for the SFTP adapter with the rm process.

Table 267

600

BMC Atrium Orchestrator Base Adapters User Guide

symlink

Table 268 Process outputsrm

Process outputs adapter response Description Specifies the SFTP adapters response

symlink
The symlink process creates a symbolic link on the remote server for a specified file. Table 269 describes the process input parameters for the SFTP adapter with the symlink process. Table 269 Process inputssymlink (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SFTPActorAdapter target Identifies the target defined in the SFTP adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to be used for remote host authentication This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

601

symlink

Table 269 Process inputssymlink (part 2 of 3)

Process input password encryption type Description Specifies the method of encryption used for the password value provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. Default value: homeDir/.ssh/known_hosts allow unknown hosts Indicates whether a connection should continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred pk algorithm Specifies the preference of the algorithm used to encrypt the public key Conditional This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa file name link Specifies the remote path, including the file name, for which a symbolic Yes link is created Specifies the name of the link for the specified file Yes Conditional Conditional Required Conditional

602

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Command Line

Table 269 Process inputssymlink (part 3 of 3)

Process input character-set Description Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target Default value: 60 seconds Required No

Table 270 describes the process output parameters for the SFTP adapter with the symlink process. Table 270 Process outputssymlink
Process output adapter response Description Specifies the SFTP adapters response

Terminal Command Line

The Command Line process invokes the command line program on a peer. Table 271 describes the process input parameters for the Command Line process. Table 271 Process inputsCommand Line (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: CommandLineAdapter command Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. Default value: echo Success No Required No

Chapter 6 Adapter utilities module

603

Terminal Command Line

Table 271 Process inputsCommand Line (part 2 of 2)

Process input commands Description Required Specifies the string that specifies the commands and any arguments for No the request You might need to provide parameters other than the command type when using the wrapper parameters like target or prompts. If you provide only the <command> parameter, a workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> s If you provide only the <commands> parameter, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands>
s

If you provide both, command and commands, the workflow executes the command provided by the user. working directory command directory command encryption type command timeout Specifies the directory in which to execute the command Default value: current directory Specifies the directory where the command is located Default value: current directory Specifies the method of encryption used for the command value provided Valid value: Base64, Plain (default) Specifies the time, in seconds, allotted to complete the execution of the command Default value: 60 seconds No No No No

Table 272 describes the process output parameters for the Command Line process. Table 272 Process outputsCommand line
Process output adapter response Description Specifies the Command Line adapters response

Table 273 Process outputsCommand line

Process output adapter response Description Specifies the Command Line adapters response

604

BMC Atrium Orchestrator Base Adapters User Guide

Terminal SSH

Terminal SSH
The SSH process issues a command on a remote SSH host using the SSH protocol. Table 274 describes the process input parameters for the SSH process. Table 274 Process inputsTerminal SSH (part 1 of 3)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default adapter: SSHAdapter target Identifies the target defined in the SSH adapter configuration (in Grid Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. port Specifies the port on which the remote host listens This input applies to a dynamic target. Default value: 22 user name Specifies the user name to use for login on the remote host This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password that corresponds to the user name provided This input applies to a dynamic target and is required if a dynamic target is used. password encryption type Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. connection name Specifies the reference name for a persistent connection This input applies to a persistent connection and is required if a persistent connection is used. Conditional No Conditional Conditional No Conditional No Required No

Chapter 6 Adapter utilities module

605

Terminal SSH

Table 274 Process inputsTerminal SSH (part 2 of 3)

Process inputs Description terminate connection Indicates whether the SSH connection must be terminated This input applies to a persistent connection. Default value: false known hosts config Identifies the path to the local known_hosts file This file is used when performing key verification. This input applies to a dynamic target. allow unknown hosts Indicates whether a connection must continue if key verification fails This input applies to a dynamic target. Valid values: true, false Default value: false Note: With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error. preferred PK algorithm Specifies the preference of the algorithm used to encrypt the public key No This input applies to a dynamic target. Valid values: ssh-dss, ssh-rsa Default value: ssh-rsa command Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. commands Specifies the string that specifies the commands and any arguments for No the request You might need to provide parameters other than the command type when using the wrapper parameters like target or prompts. If you provide only the <command> parameter, a workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> s If you provide only the <commands> parameter, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands> s If you provide both, command and commands, the workflow executes the command provided by the user.
s

Required No

No

No

No

606

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos

Table 274 Process inputsTerminal SSH (part 3 of 3)

Process inputs Description command timeout Specifies the time, in seconds, allotted to complete the execution of the command Default value: 60 seconds command encryption type prompt prompts character-set Specifies the method of encryption used for the command value provided Valid value: Base64, Plain (default) Specifies the console prompt displayed when the system is waiting for a No command Specifies an XML document containing the prompts used to enable and No interact with a device Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 establishconnectiontimeout-secs Specifies the timeout, in seconds, for the connection to be established on No the target No No Required No

Table 275 describes the process input parameters for the SSH process. Table 275 Process outputsTerminal SSH
Process output adapter response Description Specifies the SSH adapters response

Terminal Kerberos
Kerberos is a mechanism used to authenticate and authorize clients securely to access available services. Under Kerberos, a client (generally a user or a service) sends a request for a ticket to the Key Distribution Center (KDC). The KDC creates a Ticket Granting Ticket (TGT) for the client, encrypts it using the client's password as the key, and sends the encrypted TGT back to the client. The client then attempts to decrypt the TGT, using its password.

Chapter 6 Adapter utilities module

607

Terminal Kerberos ticket properties

If the client successfully decrypts the TGT (if the client specifies the correct password), the client keeps the decrypted TGT, which indicates proof of the client's identity. The TGT, which expires at a specified time, permits the client to obtain additional tickets, which give permission for specific services. The requesting and granting of these additional tickets is transparent to the user.

Terminal Kerberos ticket properties

s

forwardable: If a ticket is forwardable, the KDC can issue a new ticket with a different network address based on the forwardable ticket. This allows authentication forwarding without having to retype a password. Example: If a user with a forwardable TGT logs into a remote system, the KDC could issue a new TGT for that user with the network address of the remote system, allowing authentication on that host to work as though the user were logged in locally. When the KDC creates a new ticket based on a forwardable ticket, it sets the forwarded flag on the new ticket. Any tickets that are created based on a ticket with the forwarded flag set also have their forwarded flags set.

proxy ticket: A proxy ticket is similar to a forwardable ticket in that it allows a

service to take on the identity of the client. Unlike a forwardable ticket, however, a proxy ticket is only issued for specific services. In other words, a TGT cannot be issued based on a ticket that is a proxy but not forwardable.
s

okay flag: The okay flag indicates that the server specified in the ticket is suitable as a delegate as determined by the policy of that realm. A server that is acting as a delegate has been granted a proxy or a forwarded TGT. This flag is a new addition to the Kerberos V5 protocol and is not yet implemented on MIT servers.

Terminal Kerberos SSH1 adapter

The Kerberos SSH1 adapter uses the local host and the matching SSH server implementation for authentication. When the adapter uses SSH1 Kerberos, the sun.security.krb5.internal.tools.Kinit class is used to obtain the Kerberos ticket before invoking the SSH client. Since authentication is requested from a KDC, which might not be the target server offering the SSH service, you need to provide a valid Kerberos Ticket Granting Ticket (TGT).

608

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos SSH1 adapter configuration with valid TGT specified

The various options available are:

s s s s

Valid TGT specified Dynamic targets SSH-optionsoptional SSH-argumentsoptional

Terminal Kerberos SSH1 adapter configuration with valid TGT specified

The ktgt-cache-file-name parameter is used to specify a valid TGT. If a valid TGT is specified, the user name and krb-realm parameters are extracted from the TGT. Figure 390 shows an XML sample of the adapter configuration for the Kerberos SSH1 adapter with the ktgt-cache-file-name parameter and a valid TGT specified. Figure 390 XML sample of the Terminal Kerberos SSH1 adapter configuration with ktgt-cache-filename parameter and a valid TGT
<config> <ktgt-cache-file-name>/tmp/KTGT-devtest</ktgt-cache-file-name> <target>matrix.bmc.com</target> <prompt>$</prompt> </config>

Table 276 on page 609 shows the adapter configuration elements for the Kerberos SSH1 adapter with the ktgt-cache-file-name parameter and a valid target specified. Table 276 Terminal Kerberos SSH1 adapter configuration elements with ktgt-cache-file-name parameter and a valid TGT
Process input ktgt-cache-filename target prompt Description Specifies the location of a valid Kerberos Ticket Granting Ticket (TGT) Specifies the host used for authentication Specifies the prompt to be used to parse the output of the terminal session Required Conditional Conditional No

If a valid TGT is specified, the user-name (client principal name) and the krb-realm parameters are extracted from the TGT.

Chapter 6 Adapter utilities module

609

Terminal Kerberos SSH1 adapter configuration with dynamic targets

Terminal Kerberos SSH1 adapter configuration with dynamic targets

Configuration options-related TGT cache files are supported for dynamic targets. Figure 391 on page 610 provides a sample Kerberos SSH1 configuration with dynamic targets. This configuration sample illustrates an option pointing to a valid TGT using the ktgt-cache-file-name parameter. Figure 391 XML sample of the Terminal Kerberos SSH1 configuration with dynamic targets
<adapter-request> <target-adapter>command adapter</target-adapter> <peer-location> <location>this</location> <peer-name>peername</peer-name> </peer-location> <request-action></request-action> <request-data> <krb-request> <targets> <target> <ktgt-cache-file-name>/tmp/KTGT-devtest</ktgt-cache-file-name> <host>dev1.abc.com</host> <prompt>$</prompt> </target> </targets> <commands> <command>cd /tmp</command> <command>pwd</command> <command>ls -la</command> <command>pwd</command> </commands> </krb-request> </request-data> </adapter-request>

Table 277 describes the configuration elements for Kerberos SSH1 adapter with dynamic targets. Table 277 Terminal Kerberos SSH1 adapter configuration elements with dynamic targets (part 1 of 3)
Element Description Required Conditional <ktgtSpecifies the name of the file used to cache the Kerberos ticket cache-filename> Default value: KTGT <prompt> Specifies the prompt to be used to parse the terminal session's output

No

610

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos SSH1 adapter configuration with dynamic targets

Table 277 Terminal Kerberos SSH1 adapter configuration elements with dynamic targets (part 2 of 3)
Element <sshoptions> Description Specifies the options in the format used in the ssh_config file The ssh_config file is located with the sshd_config file in the /etc/ssh or /etc directory. One command line option for an SSH client executable is the -o option. This is useful for specifying options for which there is no separate command-line flag. Sample configuration: <config> <ktgt-cache-file-name>/tmp/KTGT-devtest</ktgt-cachefile-name> <target>dev7.bmc.com</target> <prompt>$</prompt> <ssh-options> <ssh-option>GSSAPIAuthentication=yes</ssh-option> <ssh-option>GSSAPIDelegateCredentials=yes</sshoption> </ssh-options> </config> <ssharguments> Specifies the arguments for the SSH command Depending on the target SSH client executable, you may need to specify the -t option multiple times. Sample configuration: <config> <user-name>devtest</user-name> <password>devtest</password> <krb-realm>ROKDC.COM</krb-realm> <kdc-name>kdc1.rokdc.com</kdc-name> <target>kdc1.rokdc.com</target> <prompt>$</prompt> <ssh-arguments> <ssh-argument>-t -t</ssh-argument> <ssh-argument>-v</ssh-argument> </ssh-arguments> </config> <sshcommand> Specifies the SSH command This value is set only when the SSH command is an alias or is located in nonstandard locations. Default value: ssh No No Required No

Chapter 6 Adapter utilities module

611

Terminal Kerberos SSH1 adapter configuration with dynamic targets

Table 277 Terminal Kerberos SSH1 adapter configuration elements with dynamic targets (part 3 of 3)
Element <commands> Description Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. <command> Specifies the string that specifies the commands and any arguments for the request You might need to provide parameters other than the command type when using the wrapper parameters like target or prompts. If you provide only the <command> parameter, a workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> s If you provide only the <commands> parameter, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands> s If you provide both, command and commands, the workflow executes the command provided by the user.
s

Required Yes

Yes

612

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos SSH2 adapter

Terminal Kerberos SSH2 adapter

This section provides information about the Terminal Kerberos SSH2 adapter configuration.

Terminal Kerberos SSH2 adapter configuration

You use the Kerberos SSH2 adapter configuration when the target SSH server supports Generic Security Services Application Programming Interface (GSS-API) based Kerberos authentication for the SSH2 protocol and uses the Java Authentication and Authorization Service (JAAS) LoginModule to authenticate and obtain a Kerberos ticket. Figure 392 illustrates a sample Kerberos SSH2 adapter configuration. Since the authentication is requested from a KDC, which might not be the target server offering the SSH service, you must provide krb-realm and kdc-name parameters.

TIP
The fully qualified domain name (FQDN) is used when specifying host names, a KDC name, and a target. Ensure that the target host in the Kerberos database has the shortened host name and not its FQDN.

Figure 392 Kerberos SSH2 configuration

<config> <user-name>devtest</user-name> <password>devtest</password> <krb-realm>ROKDC.COM</krb-realm> <kdc-name>kdc1.rokdc.com</kdc-name> <target>dev.bmc.com</target> <prompt>$</prompt> </config>

Table 278 on page 614 describes the configuration elements for the Kerberos SSH2 adapter.

Chapter 6 Adapter utilities module

613

Terminal Kerberos SSH2 adapter configuration with krb-realm

Terminal Kerberos SSH2 adapter configuration with krb-realm

When the krb-realm parameter is specified, the value of the default_realm parameter in the Kerberos configuration file is ignored. Figure 393 shows the adapter configuration for the Kerberos SSH2 adapter with the krb-realm parameter. Figure 393 XML sample of the Terminal Kerberos SSH2 adapter configuration with krb-realm
<config> <user-name>admintest</user-name> <password>servertest</password> <krb-realm>RODC.COM</krb-realm> <target>server7.myserver.com</target> <prompt>$</prompt> </config>

Terminal Kerberos SSH2 adapter configuration elements

Table 278 describes the Kerberos SSH2 configuration elements. Table 278 Terminal Kerberos SSH2 configuration elements (part 1 of 2)
Element <config> <user-name> <password> <kdc-name> Description Contains the elements of the configuration Specifies the name of the user registered as a Kerberos user principal Specifies the password set in the Kerberos database for the principal user Specifies the name of the host acting as the Key Distribution Center (KDC) The Java API uses this value for accessing the KDC information. Note: If the value for this element is not reflected after updating the configuration, restart the peer. <krb-realm> <target> <prompt> <use-subjectcredentials> Specifies the name of the Kerberos realm Specifies the host used for authentication Specifies the prompt used to parse the output of the terminal session Specifies whether to use the subject credentials If this parameter is set to false, the adapter does not acquire the credentials using Java Authentication and Authorization Service (JAAS) APIs and uses kinit to get the initial credentials. If this parameter is set to true, the adapter acquires the credentials using JAAS. Default value: true Conditional Conditional No No Required Yes Conditional Conditional Conditional

614

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos SSH2 adapter configuration with dynamic targets

Table 278 Terminal Kerberos SSH2 configuration elements (part 2 of 2)

Element <krb5-loginconfig-file> Description Specifies the .properties file that defines the JAAS-related implementation that the adapter uses for authentication The default contents of this properties file are: com.sun.security.jgss.initiate {com.sun.security.auth.module.Krb5LoginModule required;}; Default value: krb5login.properties file in classpath <krb5-debug> Specifies the debug level logging Valid values: true, false Default value: false No Required No

Terminal Kerberos SSH2 adapter configuration with dynamic targets

Figure 394 shows a Kerberos SSH2 adapter configuration with dynamic targets. Figure 394 XML sample of the Terminal Kerberos SSH2 adapter configuration with dynamic targets
<adapter-request> <target-adapter>kerberos ssh adapter</target-adapter> <peer-location> <location>this</location> <peer-name>peername</peer-name> </peer-location> <request-action></request-action> <request-data> <krb-request> <targets> <target> <user-name>devtest</user-name> <password>devtest</password> <krb-realm>ROKDC.COM</krb-realm> <kdc-name>kdc1.rokdc.com</kdc-name> <host>devA.bmc.com</host> <prompt>$</prompt> </target> </targets> <commands> <command>cd /tmp</command> <command>pwd</command> <command>ls -la</command> <command>pwd</command> </commands> </krb-request> </request-data> </adapter-request>

Chapter 6 Adapter utilities module

615

Terminal Kerberos SSH2 adapter configuration with dynamic targets

Figure 395 on page 616 shows a sample configuration that does not specify a TGT. This configuration requests authentication from the KDC, which may not be the target server with the SSH service. You must specify the location of the Kerberos configuration file containing the default realm name.

NOTE
The fully qualified domain name (FQDN) is used when specifying host names, a KDC name, and a target. Ensure that the target host in the Kerberos database has the shortened host name and not its FQDN.

Figure 395 XML sample of the Terminal Kerberos SSH2 adapter configuration with dynamic targets using user name and password
<adapter-request> <target-adapter>command adapter</target-adapter> <peer-location> <location>this</location> <peer-name>peername</peer-name> </peer-location> <request-action></request-action> <request-data> <krb-request> <targets> <target> <user-name>devtest</user-name> <password>devtest</password> <krb-realm>MYREALM.COM</krb-realm> <host>server7.myserver.com</host> <prompt>$</prompt> </target> </targets> <commands> <command>cd /tmp</command> <command>pwd</command> <command>ls -la</command> <command>pwd</command> </commands> </krb-request> </request-data> </adapter-request>

616

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Kerberos SSH2 adapter configuration elements with dynamic targets

Terminal Kerberos SSH2 adapter configuration elements with dynamic targets

Table 279 describes the configuration elements for the Kerberos SSH2 adapter with dynamic targets. Table 279 Terminal Kerberos SSH2 configuration elements with dynamic targets (part 1 of 2)
Element <adapterrequest> <target adapter> <peerlocation> <location> <requestaction> <requestdata> <targets> <user-name> <password> <krb-realm> Description Contains the elements of the adapter request Specifies the adapter to use in the request Contains the elements used to identify the peer Specifies the peer location Specifies the action for the request Contains the data information for the request Contains the information about the targets Specifies the name of the user registered as a Kerberos user principal Specifies the password set in the Kerberos database for the principal user Specifies the name of the Kerberos realm If you specify a valid ktgt-cache-file-name parameter, this element is ignored. <kdc-name> <target> <prompt> <commands> Specifies the name of the host acting as a Key Distribution Center (KDC) Specifies the host used for authentication Specifies the prompt used to parse the output of the terminal session. Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. Conditional Conditional No Yes Required Yes No No No No Yes Conditional Conditional Conditional Conditional

Chapter 6 Adapter utilities module

617

Terminal Kerberos SSH2 adapter configuration elements with dynamic targets

Table 279 Terminal Kerberos SSH2 configuration elements with dynamic targets (part 2 of 2)
Element <command> Description Specifies the string that specifies the commands and any arguments for the request You might need to provide parameters other than the command type when using the wrapper parameters like target or prompts. If you provide only the <command> parameter, a workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> s If you provide only the <commands> parameter, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands> s If you provide both, command and commands, the workflow executes the command provided by the user.
s

Required Yes

Default command: echo Success <useSpecifies whether to use the subject credentials subjectcredentials> If this parameter is set to false, the adapter does not acquire the credentials using Java Authentication and Authorization Service (JAAS) APIs and uses kinit to get the initial credentials. If this parameter is set to true, the adapter acquires the credentials using JAAS. Default value: true <krb5-login- Defines the JAAS related implementation for authentication that must be config-file> used The default content of this properties file is as follows: com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required; }; Default value: krb5login.properties in the classpath <krb5-debug> Specifies whether to enable debugging for Kerberos Valid values: true, false Default value: false No No No

618

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Telnet

Terminal Telnet
The Telnet adapter process issues a command on a remote Telnet server using the Telnet protocol. Table 280 describes the process input parameters for the Telnet adapter process. Table 280 Process inputsTelnet (part 1 of 3)
Process input adapter name Description Specifies the name of the adapter to use for this process This input applies to a dynamic target and is required if a dynamic target is used. Default value: TelnetAdapter target Identifies the target defined in the Telnet adapter configuration (in Grid No Manager) If you do not specify a value for this input, the first node in the adapter configuration is used. host name port Specifies the host name or the IP address of the remote host Specifies the port on which the remote Telnet server listens This input applies to a dynamic target. Default value: 23 user name Specifies the user name to use for login on the remote host This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password to use for login on the remote host This input applies to a dynamic target and is required if a dynamic target is used. login prompt password prompt password encryption type Specifies the prompt used for login Specifies the prompt used for entering the password Specifies the method of encryption used for the password provided This input applies to a dynamic target. Valid values: Base64, Plain Default value: Plain Note: If the <password encryption type> element is Base64, the password that you provide must be a Base64 encoded value. If the <password encryption-type> element is Plain, the password that you provide must be in Plain text. No No Conditional Conditional Conditional Conditional No Required No

Chapter 6 Adapter utilities module

619

Terminal Telnet

Table 280 Process inputsTelnet (part 2 of 3)

Process input connection name Description Specifies the reference name for a persistent connection This input applies to a persistent connection and is required if a persistent connection is used. terminate connection Indicates whether the Telnet connection must be terminated This input applies to a persistent connection. Valid values: true, false Default value: false commands Specifies an XML document that contains the commands in the request The wrapper process does not check the XML syntax. command Specifies the string that specifies the commands and any arguments for No the request You might need to provide parameters other than the command type when using the wrapper parameters like target or prompts. If you provide only the <command> parameter, a workflow generates from the other command inputs and executes: <command prompt=promplt1ignore-exitcode=true>cmd1</command> s If you provide only the <commands> parameter, the workflow uses the provided commands in the following format: <commands> <command prompt=promplt1ignore-exitcode=true>cmd1</command> <command>cmd2</command> <command>cmd3</command> </commands> s If you provide both, command and commands, the workflow executes the command provided by the user.
s

Required Conditional

No

No

Default command: echo Success command encryption type command timeout Specifies the method of encryption used for the command value provided Valid value: Base64, Plain (default) Specifies the time, in seconds, allotted to complete the execution of the command Default value: 60 seconds No No

620

BMC Atrium Orchestrator Base Adapters User Guide

Terminal Windows Command

Table 280 Process inputsTelnet (part 3 of 3)

Process input prompt Description Required Specifies the console prompt displayed when the system is waiting for a No command (the terminating string, typically ending with a $, >, or # , as defined by the $PS1 or %PROMPT% environment variable for a specific user's default login session). The specified value must be CDATA wrapped if the string contains a $ or a >. prompts character-set Specifies an XML document containing the prompts used to enable and No interact with a device Specifies the name of the Character set used to encode or decode the characters This input applies to a dynamic target and is required if a dynamic target is used. For example, Shift_JIS supports the Japanese character set and Big5 supports the traditional Chinese character set. Default value: ISO-8859-2 No

Table 281 describes the process output parameters for the Telnet adapter. Table 281 Process outputsTelnet
Process output adapter response Description Specifies the Telnet adapters response

Terminal Windows Command

The Windows Command adapter process issues a command on a remote Microsoft Windows server. Table 282 describes the process input parameters for the Windows Command adapter. Table 282 Process inputsWindows command (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: WindowsCommandAdapter command Specifies the command to issue, along with any arguments Default value: echo Success No Required No

Chapter 6 Adapter utilities module

621

Web Service

Table 282 Process inputsWindows command (part 2 of 2)

Process input command timeout Description Specifies the time, in seconds, allotted to complete the execution of the command Default value: 60 seconds host name Specifies the host name or the IP address of the remote host This input applies to a dynamic target and is required if a dynamic target is used. user name Specifies the user name to use for login on the remote host This input applies to a dynamic target and is required if a dynamic target is used. password Specifies the password to use for login on the remote host This input applies to a dynamic target and is required if a dynamic target is used. Conditional Conditional Conditional Required No

Table 283 describes the process output parameters for the Windows Command adapter. Table 283 Process outputsWindows command
Process output adapter response Description Specifies the Windows Command adapters response

Web Service
The Web Service adapter contains the following processes:
s

Make SOAP request (method one) Make SOAP request (method two) Poll Asynchronous Method

Make SOAP requestmethod one

This method issues a SOAP request against a remote SOAP server.

622

BMC Atrium Orchestrator Base Adapters User Guide

Make SOAP requestmethod one

Table 284 describes the process input parameters for the Web Services adapter with Make SOAP requestmethod one. Table 284 Process inputsMake SOAP requestmethod one (part 1 of 2)
Process inputs Description adapter name Specifies the name of the adapter to use for this process Default value: SOAPAdapter transport Identifies the transport protocol to use for the message Valid value: http-rpc (default), https-rpc soap url Specifies the URL for the remote SOAP service Valid values:
s s

Required No

No

Yes

http://x.y https://x.y Yes

soap message content type

Specifies the fully formatted SOAP message to transmit

Specifies the Internet media type of the message content, consisting of a No type and subtype Valid values: TEXT, XML

soap action

Specifies the SOAPAction HTTP request header field that you can use to No indicate the intent of the SOAP HTTP request The value is a URI identifying the intent. SOAP places no restrictions on the format, specificity of the URI, or that it is resolvable. An HTTP client must use this header field when issuing a SOAP HTTP request. Default value: POST

use ssl certificate

Specifies whether to establish a secure connection Valid values: true, false Default value: false

No

install certificate

Specifies whether to install certificates Valid values: true, false Default value: false

No

allow unsigned certificate

Specifies whether to allow unsigned certificates from trusted zones Valid values: true, false Default value: false

No

truststore file

Specifies the path to the truststore file containing the CAs Default value: Java standard truststore

No

Chapter 6 Adapter utilities module

623

Make SOAP requestmethod two

Table 284 Process inputsMake SOAP requestmethod one (part 2 of 2)

Process inputs Description pass phrase Specifies the Java standard Trust Key Store pass phrase Default value: changeit keystore file keystore pass phrase client alias Specifies the path to the keystore containing the client certificate Specifies the password of the keystore file Default value: changeit Specifies the alias name in the keystore that identifies the Public Key Certificate (PKC), the web server uses to authenticate the client No No No Required No

Table 285 describes the process output parameters for the Web Services adapter with Make SOAP requestmethod one. Table 285 Process outputsMake SOAP requestmethod one
Process output adapter response Description Specifies the Web Services adapters response

Make SOAP requestmethod two

This method issues a SOAP request against a remote SOAP server. This SOAP request method relies on the adapter to implement SOAP and requires only the header and the body payloads to be specified. This method supports HTTPS. Table 284 describes the process input parameters for the Web Services adapter with Make a SOAP request. Table 286 Process inputsMake SOAP requestmethod two (part 1 of 2)
Process input adapter name Description Specifies the name of the adapter to use for this process Default value: SOAPAdapter soap url Specifies the URL for the remote SOAP service Valid formats:
s s

Required No

Yes

http://x.y https://x.y No No No

username password soap action

Specifies the user name to use for login on the remote host Specifies the password to use for login on the remote host Specifies the action to be performed by the SOAP request

624

BMC Atrium Orchestrator Base Adapters User Guide

Make SOAP requestmethod two

Table 286 Process inputsMake SOAP requestmethod two (part 2 of 2)

Process input soap version Description Specifies the SOAP version to use Valid values: 1.1, 1.2 Default value: 1.1 soap header content soap body content connection name Contains specific header content, as required by the web service Contains the specific body content as required by the web service Specifies the reference name for a persistent connection This input applies to a persistent connection and is required if a persistent connection is used. terminate on exit Indicates whether the SOAP connection must be terminated This input applies to a persistent connection. Default value: false No No Yes Conditional Required No

Table 287 describes the process input parameters for the Web Services adapter with a Make SOAP request. Table 287 Process outputsMake SOAP request method two
Process output adapter response Description Specifies the Web Services adapter response

Chapter 6 Adapter utilities module

625

Make SOAP requestmethod two

626

BMC Atrium Orchestrator Base Adapters User Guide

Appendix

Troubleshooting
This appendix provides information about generic adapter troubleshooting. Adapter troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 Debug-level adapter logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

Adapter troubleshooting
The general troubleshooting steps for an adapter are:

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 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 Development Studio, the adapter requests and
responses are logged in the processes.log file for the Development Studio.
t

NOTE

The processes.log file for the grid is located in the AO_HOME\tomcat\logs directory and the processes.log file for the 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.

Appendix A

Troubleshooting

627

Debug-level adapter logging

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. See the
configuration format specified in Configuring the adapter on page 14.

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 above steps helps 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 Log on to the Grid Manager. 1 Click the Manage tab, and click the Peers tab. 2 From the currently defined peers for the Grid, select the peer on which the adapter
is enabled, and click Edit .

3 On the Edit a Peer Configuration page, click Configure Logging. 4 On the Edit Logging Levels on Peer page, set the Logging Level to DEBUG for
Adapter Framework, Adapters, Library Manager and Configuration.
s

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.

5 Click OK.

628

BMC Atrium Orchestrator Base Adapters User Guide

Debug-level adapter logging

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

Appendix A

Troubleshooting

629

Debug-level adapter logging

630

BMC Atrium Orchestrator Base Adapters User Guide

Appendix

Using ActivePerl scripts in a Windows environment

B

This appendix explains how to use ActivePerl scripts in a Windows environment.

To successfully execute ActivePerl scripts in a Windows environment 1 Locate the Dumper.pm file within the ActivePerl installation directory.
The default location is C:/Perl/lib/Data/Dumper.pm

2 Open the Dumper.pm file in Notepad. 3 Go to line containing the following text:
sprintf our $refaddr_format, Scalar::Util::refaddr(shift);

4 Comment the line as indicated below:

# sprintf our $refaddr_format, Scalar::Util::refaddr(shift);

5 Save the changes to the file and close Notepad. 6 Create the Script adapter and enable it on a peer using Grid Manager.

Appendix B

Using ActivePerl scripts in a Windows environment

631

632

BMC Atrium Orchestrator Base Adapters User Guide

Appendix

Using IMW for SQL actor adapter operations

C

This appendix explains how to use the Integration Mapping Wizard (IMW) activity to perform basic operations like Insert, Update, Delete, and Select using the SQL actor adapter.

To use the IMW for SQL operations 1 Enable the SQL actor adapter version 7.6.05 on the grid.
You can configure the SQL actor adapter for single and multiple targets. The following figure shows a sample adapter configuration.
<configs> <config name="config1-oracle"> <target>10.128.248.78</target> <port>1521</port> <user-name>bmcadmin</user-name> <password>abc123</password> <subprotocol>oracle:thin</subprotocol> <database>testdb</database> <driver>oracle.jdbc.driver.OracleDriver</driver> </config> <config name="sybasedb"> <target>10.128.249.21</target> <url>jdbc:sybase:Tds:10.128.249.21:5000/MASTER</url> <user-name>sa</user-name> <driver>com.sybase.jdbc3.jdbc.SybDriver</driver> <password /> <database>master</database> </config> </configs>

2 Create a new process and drag the Integration Mapping activity from the Activity
palette to the process window and map it with the Start and End activities.

Appendix C

Using IMW for SQL actor adapter operations

633

3 Double-click the Integration Mapping activity.

This action sends a request to the grid and lists the adapters that support an IMW request (in this case, SqlActorAdapter).

4 Select SqlActorAdapter.
The adapter lists the operations that can be performed using IMW, such as, Insert Query, Update Query, Select Query, and Delete Query.

5 Select the operation you want to perform and then, click Go (in this case, Insert
Query).

The adapter lists the targets that you would have configured as shown in the figure in step 1 on page 633.

6 Select the target on which you want to send the request and then, click Go.
634 BMC Atrium Orchestrator Base Adapters User Guide

The adapter lists the tables available in the selected database.

NOTE
SQL IMW does not support dynamic targets. In other words, you can not define the targets at request time.

7 Select the table on which you want to perform the operation and then, click Go.

Appendix C

Using IMW for SQL actor adapter operations

635

The adapter displays a grid including the details of the database table selected.

8 Specify inputs for Field Name, Required, Datatype, and Input Value to insert data in
the selected table. You can enter the data or map the context value in the Input Value column. The fields marked as Required are a must.
Insert Query screen

636

BMC Atrium Orchestrator Base Adapters User Guide

NOTE
For the Insert Query operation, you do not have to enclose the input data in single quotes (') for the following text-based data types:
s s s s s s s s s s s s s s s

Bigit Boolean Double Float Integer Null Numeric Char Varchar Varchar2 Date DateTime Timestamp String Text

However, if the input data is of any other data type other than the above list, you must enclose the input data in single quotes ('). For example, you might have to specify an input value as, 'Test User Name'.

This following screen depends on the operation selected in step 5 on page 634.

Appendix C

Using IMW for SQL actor adapter operations

637

Select Query screen

For the Select Query operation, the table contains the fields shown in the Insert Query screen, and two additional fields, ALL and Where.
s

If you want to select all the rows in the table, set the value of All = true. This is equivalent to: Select * from Table_Name. If you want to select specific columns from the table, mark the fields as true. For example, setting employee_id, employee_name, and employee_email = true, is equivalent to Select employee_id, employee_name, employee_email from Table_Name.

NOTE
For all the fields, the default value is false. Therefore, if you do not set any fields to true, an exception occurs. If you set both the fields, Name and All (keyword), to true, All takes precedence and the query is equivalent to Select * from Table_Name. Hence, to select specific columns, set All to false or leave it blank.

To filter records based on certain criteria, use the Where keyword and, specify the criteria for selection, for example, Where employee_id = 2001. To define a complex criteria, use operators like =, !=, <, >, <=, >=, AND, OR, LIKE, and so on. You can specify the Where clause by selecting all the columns or specific columns.

638

BMC Atrium Orchestrator Base Adapters User Guide

Update Query screen

For The Update Query operation, the adapter displays a list of table fields (marked as Not Required) and Where clause (marked as Required). The Where clause is required for the Update Query operation. The adapter considers input values that you specify as new values which, are updated with a valid Where clause.

NOTE
Similar to the Insert Query operation, you might have to provide the values for text-based data types in single quotes (').

Appendix C

Using IMW for SQL actor adapter operations

639

Delete Query Screen

For the Delete Query operation, the adapters displays a Where clause (marked as Required). The Where clause is required for the Delete Query operation. To delete all the records from the table, specify the Where clause as true for all the rows.

640

BMC Atrium Orchestrator Base Adapters User Guide

9 Map the adapter response for the context item and then, click Finish.

Appendix C

Using IMW for SQL actor adapter operations

641

10 optional. Set the logging for the context variables. 11 Click Test Workflow or F3 to execute the operation.

642

BMC Atrium Orchestrator Base Adapters User Guide

Appendix

Creating adapter modules using the Web Services base adapter

D

This appendix explains how to create an adapter module using the Web Services base adapter.

To create an adapter module using the Web Services base adapter. 1 Create and configure the Web Services adapter on the grid. For details, see the
Web Services adapter on page 437.

2 Use Make SOAP Request Method One, if the Web Service runs on HTTP or
HTTPS.

3 Use Make SOAP Request Method Two, if the Web Service runs on HTTP and
requires a session cookie.

Appendix D

Creating adapter modules using the Web Services base adapter

643

4 Identify and perform the Web Services operations with the required inputs and
outputs using the SoapUI utility (www.soapui.org).

5 Search and import the required WSDL from the web in the SoapUI utility to get all
the operations.

6 Run the required operation

This formulates the SOAP body which includes operation names and the outputs.

7 Create a new adapter utilities module.

8 Create a process similar to the operation name. For example, create a BMC Atrium
Orchestrator process, Login for the login operation.

9 For this example, you need session cookies. Therefore, add connection name as an
input, in addition to adapter name and soap url.

644

BMC Atrium Orchestrator Base Adapters User Guide

10 Add the information needed for the operation.

For example, for the login operation, add username and password as inputs.

11 Construct a SOAP body using the Assign activity from the Activity palette to
transform an empty XML document </mt>.

Appendix D

Creating adapter modules using the Web Services base adapter

645

12 Add the inputs of operations as tokens within the XSLT transform. 13 Create a <body> element. 14 Create a child element with the same name as the operation (as seen in SoapUI).
the prefix is urn the namespace is urn:NSConfig

15 Each additional element is an input name accompanied by the token value.

646

BMC Atrium Orchestrator Base Adapters User Guide

16 Preview the SOAP body.

17 Save, exit, and assign to the output context item of the SOAP <body> element. 18 Assign inputs to the SOAP Method process.
Appendix D Creating adapter modules using the Web Services base adapter 647

19 Assign the process output to a local context item.

20 Create appropriate outputs by adding local context items to the output of the
process.

648

BMC Atrium Orchestrator Base Adapters User Guide

21 optional. With another Assign activity, extract values from the SOAP process and
pass it to the output of the process.

22 Create another module using step 1 on page 643 to step 21 on page 649.

Appendix D

Creating adapter modules using the Web Services base adapter

649

650

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index
Symbols
488 working-dir 26 Command encryption 30 command encryption 30 command line adapter 60 configuration 60 request elements 63, 83, 88, 92 response elements 65 Command Line adapter configuration character-set 61 Command Line adapter request command 63 commands 63 env-variable 63 env-variables 63 name 63 value 63 Command Line adapter request attributes run-as feature (Linux or UNIX) password 88 run-as 88 user-name 88 run-as feature (Windows) password 83 run-as 83 user-name 83 wait-for-command-output 83 run-as feature with Kerberos authentication (Linux or UNIX) krb-authentication 92 krb-command 93 krb-options 93 run-as 92 user-name 92 Command Line adapter response command 65 command-dir 65 command-output 65 command-result 65 commands-output 65 error 65, 66 execution-milliseconds 65 exit-code 66 line 66 line-count 65 metadata 65 os-arch 65

A
Actor Adapter requests and responses 330 Actor adapter 13 Actor adapter request element location 20 peer-location 20 peer-name 20 request-action 20 request-data 20 target-adapter 20 Ad Hoc Query 521 Ad Hoc Update 523 Adapter 13 Adapter request 16 Adapter response, sample 334 Append 535 append 540 application adapters 13

B
base adapter 13 BMC Software, contacting 2

C
Call adapter activity properties Action 18 Adapter Data 19 Adapter Input 19 Adapter Name 18 Adapter Output 19 Peer Location 18 Peer Name 18 cdup 543 Command attributes 26 Command attributes for Directories 26 Command attributes for directories command-dir 26

Index

651

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
os-id 65 os-version 65 output 66 request-metadata 65 status 65, 66 target-metadata 65 target-output 65 targets-output 65 working-dir 65 Common 504 Continue on failure 31 conventions, documentation 10 customer support 2 filetype 54 line 54 lines 54 File adapter response with append action error 57 execution-milliseconds 57 metadata 57 output 57 status 57 File adapter response with delete action error 59 execution-milliseconds 59 metadata 59 output 59 status 59 File adapter response with read action and no tokenization error 50 execution-milliseconds 50 line 50 lines 50 metadata 50 output 50 status 50 File adapter response with read action and tokenization header as false execution-milliseconds 51 field 51 line 51 lines 51 metadata 51 output 51 status 51 File adapter response with read action and tokenization header as true error 52 execution-milliseconds 52 field 53 line 53 lines 52 metadata 52 output 52 status 52 File adapter response with read action XML file type 49 execution-milliseconds 49 metadata 49 output 49 status 49 File adapter response with write action error 55 metadata 55 output 55 status 55 file adapter with append action request elements 56 response elements 57 file adapter with delete action

D
Delete 525, 536 Disable line termination 31 Dynamic targets 25

E
electronic documentation 9 Email / SMTP Send Email 505

F
Fat Commands 27 File adapter error 49, 51 execution-milliseconds 55 filename 47 file adapter 46 configuration 46 request 47 response elements for delete action 59 response elements for read action 49 file adapter read action with no tokenization request elements 50 File adapter request with append action character-set 56 filename 56 line 56 lines 56 File adapter request with delete action filename 58 File adapter request with read action character-set 47 delimiter 47 filetype 47 header 47 tokenize 47 File adapter request with write action 53 character-set 54 filename 54

652

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
request elements 58 response elements 59 file adapter with read action request elements 47 file adapter with read action and tokenization as false response elements 51 file adapter with read action and tokenization as true request elements 52 file adapter with write action request elements 54 response elements 55 FTP adapter 164 commands 167 configuration 165 configuration node elements 165 error 195 request elements with append command 169, 173 request elements with cdup command 176 request elements with get command 179 request elements with ls command 182 request elements with mkdir command 187 request elements with mode command 190 request elements with put command 193 request elements with pwd command 196 request elements with rename command 200 request elements with rm command 203 request elements with rmdir command 206 request elements with stat command 209 request-metadata 194 response elements with append command 171 response elements with cd command 174 response elements with get command 180 response elements with ls command 184 response elements with mkdir command 188 response elements with mode command 191 response elements with put command 194 response elements with pwd command 198 response elements with rename command 201 response elements with rm command 204 response elements with rmdir command 207 response elements with stat command 211 sample configuration 166, 167 status 194 target-metadata 195 target-output 195 targets-output 195 FTP adapter command append 167 cd 167 cdup 167 get 167 ls 167 mkdir 167 mode 167 put 167 pwd 167 rename 167 rm 167 rmdir 168 stat 168 FTP adapter configuration character-set 166 password 165 port 165 target 165 timeout-secs 166 user-name 165 FTP adapter request with append command append 170 character-set 170 commands 169 data-transfer-mode 169 local-file 170 remote-file 170 target 169 targets 169 FTP adapter request with cd command cd 173 character-set 173 commands 173 data-transfer-mode 173 target 173 targets 173 FTP adapter request with cdup command cdup 176 character-set 176 commands 176 data-transfer-mode 176 target 176 targets 176 FTP adapter request with get command character-set 179 commands 179 data-transfer-mode 179 get 179 local-file 179 remote-file 179 target 179 targets 179 FTP adapter request with ls command character-set 183 commands 182 data-transfer-mode 182 ls 183 target 182 targets 182 FTP adapter request with mkdir command character-set 187 commands 187 data-transfer-mode 187 mkdir 187 target 187 targets 187 FTP adapter request with mode command

Index

653

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
character-set 190 commands 190 data-transfer-mode 190 mode 190 target 190 targets 190 FTP adapter request with put command character-set 193 commands 193 data-transfer-mode 193 local-file 193 put 193 remote-file 193 target 193 targets 193 FTP adapter request with pwd command character-set 197 commands 197 data-transfer-mode 197 pwd 197 target 196 targets 196 FTP adapter request with rename command character-set 200 commands 200 data-transfer-mode 200 new-file 200 old-file 200 rename 200 target 200 targets 200 FTP adapter request with rm command character-set 203 commands 203 data-transfer-mode 203 rm 203 target 203 targets 203 FTP adapter request with rmdir command character-set 206 commands 206 data-transfer-mode 206 rmdir 206 target 206 targets 206 FTP adapter request with stat command character-set 210 commands 210 data-transfer-mode 210 stat 210 target 209 targets 209 FTP adapter response with append command command 171 command-output 171 commands-output 171 error 171, 172 execution-milliseconds 171 id 171 metadata 171 output 172 request-metadata 171 status 171 target-metadata 171 target-output 171 targets-output 171 FTP adapter response with cd command command 175 command-output 174 commands-output 174 error 174, 175 execution-milliseconds 175 id 175 metadata 175 output 175 request-metadata 174 status 174, 175 target-metadata 174 target-output 174 targets-output 174 FTP adapter response with cdup command command 178 command-output 178 commands-output 178 error 177, 178 execution-milliseconds 178 id 178 metadata 178 output 178 request-metadata 177 status 177, 178 target-metadata 177 target-output 177 targets-output 177 FTP adapter response with get command command 181 command-output 181 commands-output 181 error 180, 181 execution-milliseconds 181 id 181 metadata 181 output 181 request-metadata 180 status 180, 181 target-metadata 181 target-output 181 targets-output 181 FTP adapter response with ls command command 184 command-output 184 commands-output 184 error 184 execution-milliseconds 184

654

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
file 184 group 185 id 184 metadata 184 modification-time 185 name 184 output 184 owner 184 permission 185 request-metadata 184 size-bytes 185 status 184 target-metadata 184 target-output 184 targets-output 184 FTP adapter response with mkdir command command 189 command-output 189 commands-output 189 error 188, 189 execution-milliseconds 189 id 189 metadata 189 output 189 request-metadata 188 status 188, 189 target-metadata 188 target-output 188 targets-output 188 FTP adapter response with mode command command 192 command-output 192 commands-output 192 error 191, 192 execution-milliseconds 192 id 192 metadata 192 output 192 request-metadata 191 status 191, 192 target-metadata 191 target-output 191 targets-output 191 FTP adapter response with put command command 195 command-output 195 commands-output 195 error 195 execution-milliseconds 195 id 195 metadata 195 output 195 status 195 FTP adapter response with pwd command command 198 command-output 198 commands-output 198 error 198 execution-milliseconds 198 id 198 metadata 198 output 198 pwd 198 request-metadata 198 status 198 target-metadata 198 target-output 198 targets-output 198 FTP adapter response with rename command command 202 command-output 202 commands-output 201 error 201, 202 execution-milliseconds 202 id 202 metadata 202 output 202 request-metadata 201 status 201, 202 target-metadata 201 target-output 201 targets-output 201 FTP adapter response with rm command command 205 command-output 205 commands-output 205 error 204, 205 execution-milliseconds 205 id 205 metadata 205 output 205 request-metadata 204 status 204, 205 target-metadata 204 target-output 204 targets-output 204 FTP adapter response with rmdir command command 208 command-output 208 commands-output 208 error 207, 208 execution-milliseconds 208 id 208 metadata 208 output 208 request-metadata 207 status 207, 208 target-metadata 207 target-output 207 targets-output 207 FTP adapter response with stat command command 211 command-output 211 commands-output 211

Index

655

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
error 211, 212 execution-milliseconds 211 id 211 metadata 211 output 212 request-metadata 211 stat 212 status 211 target-metadata 211 target-output 211 targets-output 211 http-connection-properties 348 install-certificate 347 ntlm authentification 346 ntlm-authentication 348 passphrase 347 use-ssl-certificate 347 HTTP adapter request with put action adapter name 352 allow unsigned certificate 352 connection properties 352 data format 352 file-path 352 install certificate 352 pass phrase 352 password 352 url 352 use ssl certificate 352 user name 352 HTTP adapter response with get action 341 HTTP adapter response with get action when data-format is HTM status-line 341 HTTP adapter response with get action when data-format is HTML code 341 field-name 342 header-lines 341 message-body 342 metadata 341 reason 341 status 341 HTTP adapter response with get action when data-format is XHTML or XML code 343 field-name 343 header-lines 343 message-body 343 reason 343 status-line 343 HTTP adapter response with post action 349 code 350 field-name 351 header-lines 350 message-body 351 metadata 350 reason 350 status 350 status-line 350 HTTP Get 505

G
Get 562 get 544, 578 get dir 575

H
Help, online 9 HTTP adapter 336 HTTP adapter configuration 337 data-format 337 host 338 password 338 port 338 proxy-settings 338 request-timeout 337 user-name 338 HTTP adapter request with delete action adapter name 354 allow unsigned certificate 354 connection properties 355 data format 355 install certificate 354 pass phrase 355 password 355 url 354 use ssl certificate 354 user name 355 HTTP adapter request with get action 339 action 339 allow-unsigned-certificate 339 data-format 339 http-connection-properties 339 install-certificate 339 ntlm-authentication 340 passphrase 339 use-ssl-certificate 339 HTTP adapter request with post action 345 action 347 allow-unsigned-certificate 347 data 346, 348 data-format 345, 348

I
Ignore response 32 IMAP mail adapter configuration allow-unsigned-certificates 483 attachment-download-directory 481

656

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
attachment-overwrite-existing 481 attachment-ttl 481 connection-timeout 480 create-subdirectory 481 delete-attachments-on-exit 482 disable-auth-login 480 disable-auth-plain 481 disk-cleanup-interval 482 email-address 480 file-name 482 file-name-filter 482 file-type 483 file-type-filter 483 ignore-attachments 481 install-certificate 483 javamail-debug 480 mail-timeout 480 max-attachment-size 482 max-pool-threads 482 passphrase 484 password 480 port 480 protocol 480 refresh 480 target 480 user-name 480 use-ssl-certificate 483 IMAP mail adapter event with attachments attachment 487 attachments 487 body 487 download-directory 487 email-address 486 email-message 486 from 486 name 487 peer-name 487 recipients 487 reply-to 487 sent-date 486 sent-epoch-milliseconds 487 subject 487 IMAP mail adapter event with attachments unable to download attachment 488 attachments 488 body 488 email-message 488 fault-message 488 from 488 name 488 recipients 488 reply-to 488 sent-date 488 sent-epoch-milliseconds 488 subject 488 IMAP mail configuration 479 Insert 526 Invoke SOAP request Tokenize string process input delimiter 504 string 504 Tokenize string process output tokens 504 is 584

J
JDBC OCI Instant Client libraries install 423 JMS 513 JMS actor adapter 362 JMS actor adapter asynchronous response error 371 execution-milliseconds 370 JMSMessageID 371 jms-response 370 metadata 370 response-data 371 status 370 JMS actor adapter configuration 363 JMS actor adapter request 365 body 366 bytes 367 character-set 367 correlation-id 366 delivery-mode 366 dest 366 expiration 366 jms-type 366 map 367 priority 366 properties 366 property 366 reply-to 366 request-response-wait-timeout 367 text 366 JMS actor adapter response 370 JMS actor adapter synchronous response error 371, 372 execution-milliseconds 371 jms-response 371 message 372 metadata 371 no-response 372 response-data 371 JMS adapter status 371 JMS adapter configuration connection-factory 363 jndi 363 number-of-retries 363 password 363

Index

657

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
retry-wait 364 synchronous-reply-destination 364 user-name 363 JMS adapter overview 358 JMS monitor adapter 373 JMS monitor adapter configuration 374 character-set 376 client-id 374 connection-factory 374 destination-context-name 374, 375 durable-subscriber-name 376 jndi 374 maximum-messages-per-second 375 message-class 375 of-retries 374 password 374 queue 374 queues 374 retry-wait 374 topic 375 topics 375 user-name 374 JMS monitor adapter event body 378 character-set 378 destination 377 header 377 JMSCorrelationID 377 JMSDeliveryMode 377 JMSExpiration 377 JMSMessageID 377 JMSPriority 377 JMSRedelivered 378 JMSReply-to 377 JMSTimestamp 377 JMSType 377 message 377 JMS Send Body 514 JMS Send Messages 515 krb-realm 119 line-termination 121 network-environment 121 password 119 port 119 prompt 120 target 119 targets 119 timeout-secs 120 user-name 119 use-subject-credentials 120 Kerberized SSH adapter configuration with local client establish-connection-timeout-secs 131 ktgt-cache-filename 129 port 129 prompt 130 ssh-argument 130 ssh-arguments 130 ssh-command 130 ssh-option 130 ssh-options 130 target 129 timeout-secs 131 Kerberized SSH adapter request command 124 commands 124 establish-connection-timeout-secs 124 host 123 kdc-name 123, 614 krb5-debug 123 krb5-login-config-file 123 krb-realm 123 line-termination 124 network-environment 124 password 123 port 123 prompt 122, 124 prompts 122 target 122 targets 122 timeout-secs 124 user-name 123 use-subject-credentials 123 Kerberized SSH adapter request with local client command 134 commands 134 Kerberized SSH adapter request with local clinet establish-connection-timeout-secs 134 host 132 ktgt-cache-file-name 132 port 132 prompt 132, 133 prompts 132 ssh-argument 133 ssh-arguments 133 ssh-command 133 ssh-option 133

K
Kerberized SSH adapter 117 configuration 119 configuration node elements 119 configuration node elements with local client 129 request elements for local client 132 request elements with Java client 122 response elements for local client 135 response elements with Java client 125 sample configuration 121 Kerberized SSH adapter configuration establish-connection-timeout-secs 121 kdc-name 120 krb5-debug 120 krb5-login-config-file 120

658

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
ssh-options 133 target 132 targets 132 timeout-secs 134 Kerberized SSH adapter response command 126 command-output 126 commands-output 126 error 125, 126 execution-milliseconds 126 exit-code 126 line 126 line-count 126 metadata 126 os-arch 126 os-id 125 os-version 125 output 126 request-metadata 125 status 125, 126 target-metadata 125 target-output 125 targets-output 125 Kerberized SSH adapter response with local client command 136 command-output 136 commands-output 136 error 135, 136 execution-milliseconds 136 exit-code 136 line 136 line-count 136 metadata 136 os-arch 136 os-id 135 os-version 136 output 136 request-metadata 135 status 135, 136 target-metadata 135 target-output 135 targets-output 135 Kerberos 607 Kerberos SS21 adapter 613 Kerberos SSH1 adapter 608 Kerberos SSH1 adapter configuration with valid TGT specified 609 Kerberos SSH2 adapter configuration 613 Kerberos SSHI adapter configuration with dynamic targets 610 Kerberos ticket properties 608 Known hosts 35 Known Hosts - optional elements allow-unknown-hosts 36 known-hosts-config 36 preferred-pk-algorithm 36

L
lpwd 582 ls 546

M
Make 624 Make a SOAP request Method One 622 mkdir 586 mkdirs 588 mode 550 Monitor adapter 14 Monitor adapter event elements data 21 event 21 source adapter 21 Multiple configuration nodes 24

O
online Help 9

P
Password encryption 30 Persistent connectivity 33 POP mail adapter 489 POP mail adapter configuration allow-unsigned-certificates 494 attachment-download-directory 492 attachment-overwrite-existing 492 attachment-ttl 492 connection-timeout 491 create-subdirectory 492 delete-after-read 491 delete-attachments-on-exit 493 disable-auth-login 491 disable-auth-plain 491 disk-cleanup-interval 493 email-address 490 file-name 493 file-name-filter 493 file-type 494 file-type-filter 494 ignore-attachments 491 install-certificate 495 javamail-debug 490 mail-timeout 490 max-attachment-size 493 max-messages-per-connection 491 max-pool-threads 493 passphrase 495 password 490

Index

659

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
port 490 protocol 490 refresh 490 target 490 user-name 490 use-ssl-certificate 494 POP mail adapter event with attachment downloaded successfully attachment 498 attachments 498 body 498 download-directory 498 email-message 497 from 497 name 498 peer-name 498 recipients 498 reply-to 498 sent-date 497 sent-epoch-milliseconds 498 subject 498 POP mail adapter event with no attachment download attachment 499 attachments 499 body 499 email-message 499 fault-message 499 from 499 name 499 recipients 499 reply-to 499 sent-date 499 sent-epoch-milliseconds 499 subject 499 POP mail configuration 489 POP mail event 497 PowerShell adapter configuration password 329 powershell-consolefile 329 powershell-version 329 script-file-path 329 target 328 user-name 328 use-userprofile 329 PowerShell adapter request command 331 commands 331 host 331 password 331 powershell-consolefile 331 powershell-version 331 target 331 targets 331 user-name 331 use-userprofile 331 Process inputs - delete adapter name 512 allow-unsigned-certificate 512 connection properties 513 data-format 512 html-syntax-correction 512 install-certificate 512 passphrase 512 password 513 url 512 user name 512 use-ssl-certificate 512 Process inputs - Get adapter name 519 community 519 host 519 oid value 0 519 oid value 1 519 oid value 2 519 oid value 3 520 oid value 4 520 port 519 retries 519 timeout 519 version 519 Process inputs - get adapter name 506 allow-unsigned-certificate 506 connection properties 507 data-format 506 install-certificate 506 passphrase 506 password 507 url 506 user name 506 use-ssl-certificate 506 Process inputs - post adapter name 508 allow-unsigned-certificate 345, 509 connection properties 509 data 508 data-format 508 install-certificate 345, 509 passphrase 345, 509 password 345, 509 url 345, 508 user name 345, 509 use-ssl-certificate 345, 508 Process inputs - put adapter name 510 allow-unsigned-certificate 510 connection properties 511 data 510 data-format 510 file path 511 install-certificate 510 passphrase 510 url 510 user name 510

660

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
use-ssl-certificate 510 Process inputs - Read adapter name 537 Process inputs - Select where 529 Process Inputs - Send Body adapter name 514 body 514 destination 514 headers 514 properties 514 request-response-wait-timeout 514 Process inputs - send email adapter name 505 body 505 cc address list 505 from address 505 subject 505 to address list 505 Process outputs - delete header lines 513 message body 513 status code 513 status reason 513 Process outputs - Get response 0 520 response 1 520 response 2 520 response 3 520 response 4 520 Process outputs - get header lines 507 message body 507 status code 507 status reason 507 Process outputs - post header lines 509 message body 509 status code 509 status reason 509 Process outputs - put header lines 511 message body 511 status code 511 status reason 511 Processes 14 product support 2 Proxy commands 34 Public key authentication 36 Public key authentication optional elements pass-phrase 37 private-key-file 37 publications, related 9 Put 564 put 592 put dir 590 pwd 554, 582, 594

R
Read 537 related publications 9 rename 556, 596 response for Actor Adapter 334 rm 557, 599 rmdir 559 Rules 14

S
sample response for Adapter 334 SCP adapter 149 configuration 150 request elements with get action 150, 154 request elements with put action 159 response elements with get action 157 response elements with put action 162 sample configuration 152, 153 SCP adapter configuration allow-unknown-hosts 151 establish-connection-timeout-secs 152 known-hosts-config 151 network-environment 152 pass-phrase 151 password 150 port 150 preferred-pk-algorithm 151 private-key-file 151 target 150 timeout-secs 151 user-name 150 SCP adapter request with get action allow-unknown-hosts 155 establish-connection-timeout-secs 155 host 154 known-hosts-config 155 local-file 155 network-environment 155 pass-phrase 154 password 154 port 154 preferred-pk-algorithm 155 private-key-file 154 remote-file 155 target 154 targets 154 timeout-secs 155 SCP adapter request with put action allow-unknown-hosts 160 establish-connection-timeout-secs 160 host 159 known-hosts-config 160 local-file 161 network-environment 161

Index

661

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
pass-phrase 160 password 159 port 159 preferred-pk-algorithm 160 private-key-file 160 remote-file 161 target 159 targets 159 timeout-secs 160 user-name 159 SCP adapter response with get action error 157, 158 execution-milliseconds 158 local-file 158 output 158 remote-file 158 request-action 158 request-metadata 157 status 157, 158 target-metadata 158 target-output 158 targets-output 157 SCP adapter response with put action error 163 execution-milliseconds 163 local-file 163 output 163 remote-file 163 request-action 163 request-metadata 162 status 162, 163 target-metadata 163 target-output 163 targets-output 163 Script adapter 380 Script adapter configuration perl-path 382 Script adapter request parameters 383 return-values 383 script 383 script-path 383 script-type 383 Script adapter response return-values 385 values 385 Select 528 Send Body 514 Send Messages 515 Session based CLI configuration 74 Session based Command Line adapter configuration character-set 74 env-variable 74 env-variables 74 name 74 value 74 SFTP adapter 216 commands 221 configuration 217 configuration node elements 217 request elements with cd command 222 request elements with chgrp command 227 request elements with get command 242 request elements with get-dir command 247 request elements with ls command 262 request elements with mkdir command 268 request elements with mkdirs command 273 request elements with put command 278 request elements with put-dir command 283 request elements with pwd command 288 request elements with rename command 293 request elements with rm command 298 request elements with symlink command 303 response elements with cd command 225 response elements with chgrp command 230 response elements with chmod command 235 response elements with chown command 240 response elements with get-dir command 250 response elements with lcd command 255 response elements with lpwd command 260 response elements with ls command 265 response elements with mkdir command 271 response elements with mkdirs command 275 response elements with put command 281 response elements with put-dir command 286 response elements with pwd command 291 response elements with rename command 296 response elements with rm command 301 sample configuration 220 SFTP adapter commands cd 221 chgrp 221 chmod 221 chown 221 get 221 get-dir 221 lcd 221 lpwd 221 ls 221 mkdir 221 mkdirs 221 put 221 put-dir 221 pwd 221 rename 221 rm 221 symlink 221 SFTP adapter configuration allow-unknown-hosts 218 character-set 219 establish-connection-timeout-secs 219 known-hosts-config 218 network-environment 219 pass-phrase 218

662

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
password 218 port 217 preferred-pk-algorithm 219 private-key-file 218 target 217 timeout-secs 218 user-name 217 SFTP adapter request with cd command allow-unknown-hosts 223 cd 223 character-set 223 commands 223 establish-connection-timeout-secs 223 host 222 known-hosts-config 223 network-environment 223 password 222 port 222 preferred-pk-algorithm 223 target 222 targets 222 timeout-secs 223 user-name 222 SFTP adapter request with chgrp command allow-unknown-hosts 228 character-set 228 chgrp 228 commands 228 establish-connection-timeout-secs 228 file 228 gid 228 host 227 known-hosts-config 227 network-environment 228 password 227 port 227 preferred-pk-algorithm 228 target 227 targets 227 timeout-secs 227 user-name 227 SFTP adapter request with chmod command allow-unknown-hosts 232 character-set 233 chmod 233 commands 233 establish-connection-timeout-secs 233 file 233 host 232 known-hosts-config 232 network-environment 233 password 232 permissions 233 port 232 preferred-pk-algorithm 233 target 232 targets 232 timeout-secs 232 user-name 232 SFTP adapter request with chown command allow-unknown-hosts 238 character-set 238 chown 238 commands 238 establish-connection-timeout-secs 238 file 238 host 237 known-hosts-config 237 network-environment 238 password 237 port 237 preferred-pk-algorithm 238 target 237 targets 237 timeout-secs 237 uid 238 user-name 237 SFTP adapter request with get command allow-unknown-hosts 242 character-set 243 commands 243 establish-connection-timeout-secs 243 get 243 host 242 known-hosts-config 242 local-file 243 network-environment 243 password 242 port 242 preferred-pk-algorithm 243 remote-file 243 target 242 targets 242 timeout-secs 242 user-name 242 SFTP adapter request with get-dir command allow-unknown-hosts 248 character-set 248 commands 248 establish-connection-timeout-secs 248 get-dir 248 host 247 known-hosts-config 247 local-dir 248 network-environment 248 password 247 port 247 preferred-pk-algorithm 248 remote-dir 248 target 247 targets 247 timeout-secs 247 user-name 247 SFTP adapter request with lcd command

Index

663

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
allow-unknown-hosts 253 character-set 253 commands 253 establish-connection-timeout-secs 253 host 252 known-hosts-config 252 lcd 253 network-environment 253 password 252 port 252 preferred-pk-algorithm 253 target 252 targets 252 timeout-secs 252 user-name 252 SFTP adapter request with lpwd command allow-unknown-hosts 258 character-set 258 commands 258 establish-connection-timeout-secs 258 host 257 known-hosts-config 257 lpwd 258 network-environment 258 password 257 port 257 preferred-pk-algorithm 258 target 257 targets 257 timeout-secs 257 user-name 257 SFTP adapter request with ls command allow-unknown-hosts 263 character-set 263 commands 263 establish-connection-timeout-secs 263 host 262 known-hosts-config 262 ls 263 network-environment 263 password 262 port 262 preferred-pk-algorithm 263 target 262 targets 262 timeout-secs 262 user-name 262 SFTP adapter request with mkdir command allow-unknown-hosts 269 character-set 269 commands 269 establish-connection-timeout-secs 269 host 268 known-hosts-config 268 mkdir 269 network-environment 269 password 268 port 268 preferred-pk-algorithm 269 target 268 targets 268 timeout-secs 268 user-name 268 SFTP adapter request with mkdirs command allow-unknown-hosts 274 character-set 274 commands 274 establish-connection-timeout-secs 274 host 273 known-hosts-config 273 mkdirs 274 network-environment 274 password 273 port 273 preferred-pk-algorithm 274 target 273 targets 273 timeout-secs 273 user-name 273 SFTP adapter request with put command allow-unknown-hosts 278 character-set 279 commands 279 establish-connection-timeout-secs 279 host 278 known-hosts-config 278 local-file 279 network-environment 279 password 278 port 278 preferred-pk-algorithm 279 put 279 remote-file 279 target 278 targets 278 timeout-secs 278 user-name 278 SFTP adapter request with put-dir command allow-unknown-hosts 284 character-set 284 commands 284 establish-connection-timeout-secs 284 host 283 known-hosts-config 283 local-dir 284 network-environment 284 port 283 preferred-pk-algorithm 284 put-dir 284 remote-dir 284 target 283 targets 283 timeout-secs 283 user-name 283

664

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
SFTP adapter request with pwd command allow-unknown-hosts 289 character-set 289 commands 289 establish-connection-timeout-secs 289 host 288 known-hosts-config 288 network-environment 289 password 288 port 288 preferred-pk-algorithm 289 pwd 289 target 288 targets 288 timeout-secs 288 user-name 288 SFTP adapter request with rename command allow-unknown-hosts 294 character-set 294 commands 294 establish-connection-timeout-secs 294 host 293 known-hosts-config 293 network-environment 294 new-file 294 old-file 294 password 293 port 293 preferred-pk-algorithm 294 rename 294 target 293 targets 293 timeout-secs 293 user-name 293 SFTP adapter request with rm command allow-unknown-hosts 299 character-set 299 commands 299 establish-connection-timeout-secs 299 host 298 known-hosts-config 298 network-environment 299 password 298 port 298 preferred-pk-algorithm 299 rm 299 target 298 targets 298 timeout-secs 298 user-name 298 SFTP adapter request with symlink command allow-unknown-hosts 304 character-set 304 commands 304 establish-connection-timeout-secs 304 file 304 host 303 known-hosts-config 303 link 304 network-environment 304 password 303 port 303 preferred-pk-algorithm 304 symlink 304 target 303 targets 303 timeout-secs 303 user-name 303 SFTP adapter response with cd command command 225 command-output 225 commands-output 225 error 225, 226 execution-milliseconds 225 id 225 metadata 225 output 226 request-metadata 225 status 225 target-metadata 225 target-output 225 targets-output 225 SFTP adapter response with chgrp command command 230 command-output 230 commands-output 230 error 230, 231 execution-milliseconds 230 id 230 metadata 230 output 231 request-metadata 230 status 230 target-metadata 230 target-output 230 targets-output 230 SFTP adapter response with chmod command command 236 command-output 236 commands-output 236 error 235, 236 execution-milliseconds 236 id 236 metadata 236 output 236 request-metadata 235 status 235, 236 target-metadata 236 target-output 236 targets-output 235 SFTP adapter response with chown command command 240 command-output 240 commands-output 240

Index

665

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
error 240, 241 execution-milliseconds 240 id 240 metadata 240 output 241 request-metadata 240 status 240 target-metadata 240 target-output 240 targets-output 240 SFTP adapter response with get command command 245 command-output 245 commands-output 245 error 245, 246 execution-milliseconds 245 id 245 metadata 245 output 246 request-metadata 245 status 245 target-metadata 245 target-output 245 targets-output 245 SFTP adapter response with get-dir command command 250 command-output 250 commands-output 250 error 250, 251 execution-milliseconds 250 id 250 metadata 250 output 251 request-metadata 250 status 250 target-metadata 250 target-output 250 targets-output 250 SFTP adapter response with lcd command command 255 command-output 255 commands-output 255 error 255, 256 execution-milliseconds 255 id 255 metadata 255 output 256 request-metadata 255 status 255 target-metadata 255 target-output 255 targets-output 255 SFTP adapter response with lpwd command command 260 command-output 260 commands-output 260 error 260, 261 execution-milliseconds 260 id 260 lpwd 261 metadata 260 output 261 request-metadata 260 status 260 target-metadata 260 target-output 260 targets-output 260 SFTP adapter response with ls command command 265 command-output 265 commands-output 265 error 265, 266 execution-milliseconds 265 file 266 filename 266 gid 266 id 265 mask 266 metadata 265 modification-time 266 output 266 permissions 266 request-metadata 265 status 265 target-metadata 265 target-output 265 targets-output 265 uid 266 SFTP adapter response with mkdir command command 271 command-output 271 commands-output 271 error 271, 272 execution-milliseconds 271 id 271 metadata 271 output 272 request-metadata 271 status 271 target-metadata 271 target-output 271 targets-output 271 SFTP adapter response with mkdirs command command 276 command-output 276 commands-output 276 error 275, 276 execution-milliseconds 276 id 276 metadata 276 output 276 request-metadata 275 status 275, 276 target-metadata 276

666

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
target-output 275 targets-output 275 SFTP adapter response with put command command 281 command-output 281 commands-output 281 error 281, 282 execution-milliseconds 281 id 281 metadata 281 output 282 request-metadata 281 status 281 target-metadata 281 target-output 281 targets-output 281 SFTP adapter response with put-dir command command 286 command-output 286 commands-output 286 error 286, 287 execution-milliseconds 286 id 286 metadata 286 output 287 request-metadata 286 status 286 target-metadata 286 target-output 286 targets-output 286 SFTP adapter response with pwd command command 291 command-output 291 commands-output 291 error 291, 292 execution-milliseconds 291 id 291 metadata 291 output 292 pwd 292 request-metadata 291 status 291 target-metadata 291 target-output 291 targets-output 291 SFTP adapter response with rename command command 296 command-output 296 commands-output 296 error 296, 297 execution-milliseconds 296 id 296 metadata 296 output 297 request-metadata 296 status 296 target-metadata 296 target-output 296 targets-output 296 SFTP adapter response with rm command command 301 command-output 301 commands-output 301 error 301 execution-milliseconds 301 id 301 metadata 301 output 301 request-metadata 301 status 301 target-metadata 301 target-output 301 targets-output 301 SFTP adapter response with symlink command command 306 command-output 306 commands-output 306 error 306, 307 execution-milliseconds 306 id 306 metadata 306 output 307 request-metadata 306 status 306 target-metadata 306 target-output 306 targets-output 306 SMTP adapter 472 SMTP adapter configuration 472 allow-unsigned-certificates 474 authenticate 472 disable-mail-interaction 473 file-name 474 file-name-filter 473 file-type 474 file-type-filter 474 install-certificate 475 javamail-debug 473 max-attachment-size 473 passphrase 475 password 473 port 472 starttls 473 target 472 user-name 473 use-ssl-certificate 474 SMTP adapter request 477 attachment 477 attachments 477 body 477 cc 477 from 477 subject 477 to 477

Index

667

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
SMTP adapter response 478 error 478 metadata 478 status 478 SNMP 519 SNMP actor adapter request with get action community 387 host 387 name 388 oid 387 port 387 retries 387 timeout 387 value 388 version 387 SNMP actor adapter request with notification action community 390 enterprise 390 generic 390 name 390 oid 390 oids 390 port 390 source-host 390 specific 390 target-host 390 type 390 value 390 SNMP actor adapter request with notification action for SNMPv2c trap community 392 name 392 oid 392 oids 392 port 392 source-host 392 target-host 392 trap-oid 392 type 392 value 392 version 392 SNMP actor adapter response with get action error 389 execution-milliseconds 389 metadata 389 name 389 oid 389 oids 389 status 389 value 389 SNMP actor adapter response with notification action error 394 execution-milliseconds 394 metadata 394 status 394 SNMP actor adapter with request get action oids 387 SNMP Get 519 SNMP monitor adapter 394 SNMP monitor adapter configuration mibs-directory 395 port 395 version 395 SNMP monitor adapter event with mibs-directory defined enterprise 396 host 396 name 396 oid 396 sysuptime 396 trap-type 396 value 396 varbind 396 varbinds 396 SNMP monitor adapter event without mib-directory definition enterprise 397 generic-trap-type 397 host 397 oid 397 specific-trap-type 397 sysuptime 397 value 397 varbind 397 varbinds 397 SOAP request, invoke, Tokenize String 504 SQL 520 SQL actor adapter 397 Oracle XMLType support 420 SQL actor adapter configuration configs 399 database 400 driver 401 evictor-idle-time-millis 401 max-connection-idle-time-millis 401 max-wait 401 min-connection-idle-time-millis 401 parameters 401 password 400 port 400 statement-terminator 400 subprotocol 400 target 400 url 399 user-name 400 SQL Actor Adapter request element ktgt-cache-file 407 SQL adapter Parameterized statements - Process Inputs - Delete adapter name 534 database 534 driver 534 enable transaction 534 host 534 password 534

668

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
port 534 statements 534 subprotocol 534 target 534 user name 534 Process inputs - Ad Hoc query adapter name 521 connection name 522 database 521 driver 521 evictor idle time millis 521 host 521 initial active connections 521 max active connections 521 max connection idle time millis 521 max idle connections 522 max wait 521 min connection idle time millis 521 min idle connections 522 password 521 port 521 sql 521 subprotocol 521 target 521 url 521 user name 521 validate connections on return 522 validate idle connections 522 validate query 522 Process inputs - Ad Hoc Update adapter name 523 connection name 524 database 523 driver 523 evictor idle time millis 523 host 523 initial active connections 523 max active connections 523 max connection idle time millis 523 max idle connections 524 max wait 523 min connection idle time millis 523 min idle connections 524 password 523 port 523 sql 523 subprotocol 523 target 523 url 523 user name 523 validate connections on return 524 validate idle connections 524 validate query 524 Process inputs - delete adapter name 525 connection name 526 database 525 driver 525 evictor idle time millis 525 host 525 max active connections 526 max connection idle time millis 525 max wait 525 min connection idle time millis 525 min idle connections 526 password 525 port 525 subprotocol 525 table 525 target 525 url 525 user name 525 validate connections on return 526 validate idle connections 526 validate query 526 where 525 Process inputs - insert adapter name 527 columns 527 connection name 528 database 527 driver 527 evictor idle time millis 527 host 527 initial active connections 527 max active connections 527 max connection idle time millis 527 max idle connections 528 max wait 527 min connection idle time millis 527 min idle connections 528 password 527 port 527 subprotocol 527 table 527 target 527 url 527 user name 527 validate connections on return 528 validate idle connections 528 validate query 528 values 527 Process inputs - Select adapter name 529 columns 530 connection name 531 database 530 driver 530 evictor idle time millis 530 group by 529 host 530 initial active connections 530 max active connections 530 max connection idle time millis 530

Index

669

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
max idle connections 530 max wait 530 min connection idle time millis 530 min idle connections 530 order by 529 password 530 port 530 subprotocol 530 table name 529 target 530 url 530 user name 530 validate connections on return 531 validate idle connections 531 validate query 530 where 529 where operator 529 where value 529 Process Inputs - Update adapter name 532 column 532 connection name 533 database 532 driver 532 evictor idle time millis 532 host 532 initial active connections 533 max active connections 532 max connection idle time millis 532 max idle connections 533 max wait 532 min connection idle time millis 532 min idle connections 533 password 532 port 532 subprotocol 532 table 532 target 532 url 532 user name 532 validate connections on return 533 validate idle connections 533 validate query 533 value 532 where 532 Process outputs - Ad Hoc query adapter response 522 Process outputs- Ad Hoc Update adapter response 524 Process outputs- Select adapter response 531 SQL adapter actor adapter configuration initial-active-connections 402 krb-service-principal 403, 428, 522, 524, 526, 528, 531, 533 ktgt-cache-file 403, 428, 522, 524, 526, 528, 531, 533 max-active-connections 401 max-idle-connections 402 min-idle-connections 402 validate-connections-on-return 402 validate-idle-connections 402 validate-query 402 SQL monitor adapter configuration database 426 driver 426 event-statement 428 event-statements 428 evictor-idle-time-millis 427 host 426 initial-active-connections 427 max-active-connections 427 max-connection-idle-time-millis 426 max-idle-connections 427 max-wait 426 min-connection-idle-time-millis 427 min-idle-connections 427 password 426 poll-interval 428 port 426 query 428 single-monitor-event 428 subprotocol 426 target 425 targets 425 url 426 user-name 426 validate-connections-on-return 427 validate-idle-connections 428 validate-query 427 SQL monitor adapter when event is false column 435 error 436 execution-milliseconds 435 metadata 435 query-executed 435 response-column-count 435 response-row-count 435 row 435 row-number 435 status 436 target-name 435 SQL monitor adapter when event is true column 433 error 433 metadata 433 query-executed 433 response-column-count 433 response-row-count 433 row 433 status 433 target-name 433 SQL parameterized statement actor adapter request data-type 412 enable-transaction 412, 413

670

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
parameter 412 parameter-set 412 parameter-sets 412 query 412 statement 412 statements 412 target 413 targets 412 value 412 SQL parameterized statement actor adapter response column 417 column-count 417 database-vendor 416 dynamic database 416 error 416, 417 metadata 417 query-executed 417 response-set 416 response-set-count 416 response-set-metadata 416 response-sets 416 result-set 417 result-sets 417 row 417 row-count 417 statement-metadata 416 statement-response 416 statement-responses 416 status 416, 417 target-metadata 416 SQL standard actor adapter request action 406 target 406 targets 406 SQL standard actor adapter response column 407 dynamic database 408 database-vendor 408 error 408 status 408 target-metadata 408 queryExecuted 407 responseColumnCount 407 responseRowCount 407 row 407 SSH adapter 98 configuration 99 configuration node elements 99 Keyboard-interactive capabilities 114 request elements 104 response elements 111 sample configuration 103 sample configuration with KBI 115 SSH adapter configuration allow-unknown-hosts 101 character-set 102 establish-connection-timeout-secs 102 known-hosts-config 101 line-termination 102 network-environment 102 pass-phrase 100 password 99 port 99 preferred-pk-algorithm 101 private-key-file 100 prompt 100 target 99 timeout-secs 101 user-name 99 SSH adapter request allow-unknown-hosts 106 character-set 108 command 108 commands 107 establish-connection-timeout-secs 107 host 105 known-hosts-config 106 line-termination 107 network-environment 107 pass-phrase 105 password 105 port 105 preferred-pk-algorithm 106 private-key-file 105 prompt 104, 105 prompts 104 target 104 targets 104 timeout-sec 106 use-psuedo-terminal 105 user-name 105 SSH adapter response command 111 command-output 111 commands-output 111 error 111, 112 execution-milliseconds 111 exit-code 112 line 112 line-count 111 metadata 111 os-arch 111 os-id 111 os-version 111 output 112 request-metadata 111 status 111, 112 target-metadata 111 target-output 111 targets-output 111 SSH KBI adapter configuration 115

Index

671

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
stat 560 support, customer 2 symlink 601 targets-output 146 Terminal 603, 605, 619, 621 Terminal / File 534 Terminal / FTP 539 Terminal / SCP 562 Terminal / SFTP 566 Terminal adapter features Multiple configuration nodes 24 terminal adapter features 23 Terminal Command Line adapter Process inputs adapter name 603 command 603 command directory 604 command encryption type 604 command timeout 604 commands 604 working directory 604 Process outputs adapter response 604 Terminal File adapter Process inputs - Read character-set 537 delimiter 537 file name 537 file type 537 header 537 Process inputs - Write adapter name 538 character-set 539 file name 538 file type 538 line 1 538 line 2 538 line 3 538 line 4 539 line 5 539 line 6 539 line 7 539 line 8 539 line 9 539 xml doc 539 Process outputs - Read adapter response 538 Process outputs - Write adapter response 539 Terminal FTP adapter 539 append 540 cd 541 Process inputs - cd adapter name 542 character-set 542 directory 542 host name 542 password 542 password encryption type 542 port 542

T
technical support 2 Telnet adapter 138 configuration 138 configuration node elements 139 request elements 142 response elements 146 sample configuration 140 Telnet adapter configuration character-set 140 login-prompt 139 password 139 password-prompt 140 port 139 prompt 139 target 139 timeout-secs 139 user-name 139 Telnet adapter request character-set 143 command 143 commands 143 host 142 login-prompt 143 password 142 password-prompt 143 port 142 prompt 142, 143 prompts 142 target 142 targets 142 timeout-secs 143 user-name 142 Telnet adapter response command 147 command-output 147 commands-output 147 error 146, 147 execution-milliseconds 147 exit-code 147 line 147 line-count 147 metadata 147 os-arch 147 os-id 146 os-version 147 output 147 request-metadata 146 status 146, 147 target-metadata 146 target-output 146

672

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
target 542 user name 542 Process inputs - cdup adapter name 543 character-set 544 host name 543 password 543 password encryption type 544 port 543 target 543 user name 543 Process inputs - get adapter name 545 character-set 546 host name 545 local file 545 password 545 password encryption type 546 port 545 remote file 545 target 545 user name 545 Process inputs - ls adapter name 547 character-set 548 directory 547 host name 547 password 547 password encryption type 548 port 547 target 547 user name 547 Process inputs - mkdir adapter name 549 character-set 550 directory 549 host name 549 password 549 password encryption type 550 port 549 target 549 user name 549 Process inputs - mode adapter name 551 character-set 552 host name 551 password 551 password encryption type 552 port 551 target 551 transfer mode 551 user name 551 Process inputs - out adapter name 553 character-set 554 host name 553 local file 553 password 553 password encryption type 554 port 553 remote file 553 target 553 user name 553 Process inputs - pwd adapter name 555 character-set 555 host name 555 password 555 password encryption type 555 port 555 target 555 user name 555 Process inputs - rename adapter name 556 character-set 557 host name 556 new file 556 old file 556 password 557 password encryption type 557 port 556 target 556 user name 556 Process inputs - rm adapter name 558 adapter response 559 character-set 558 host name 558 password 558 password encryption type 558 path and filename 558 port 558 target 558 user name 558 Process inputs - rmdir adapter name 559 character-set 560 directory 559 host name 559 password 559 password encryption type 560 port 559 target 559 user name 559 Process inputs - stat adapter name 561 character-set 561 file name 561 host name 561 password 561 password encryption type 561 port 561 target 561 user name 561

Index

673

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Process outputs - cd adapter response 543 Process outputs - cdup adapter response 544 Process outputs - get adapter response 546 Process outputs - ls adapter response 548 Process outputs - mkdir adapter response 550 Process outputs - mode adapter response 552 Process outputs - out adapter response 554 Process outputs - pwd adapter response 556 Process outputs - rename adapter response 557 Process outputs - rmdir adapter response 560 Process outputs - stat adapter response 562 Terminal Kerberos SSH1 adapter Configuration elements with dynamic targets command 612 commands 612 ktgt-cache-file-name 610 prompt 610 ssh-arguments 611 ssh-command 611 ssh-options 611 Configuration elements with valid targets ktgt-cache-file-name 609 prompt 609 target 609 Terminal Kerberos SSH2 adapter Configuration elements config 614 kdc-name 614 krb5-debug 615 krb5-login-config-file 615 krb-realm 614 password 614 prompt 614 target 614 user-name 614 use-subject-credentials 614 Configuration elements with dynamic targets adapter-request 617 command 617 commands 618 kdc-name 617 krb5-debug 618 krb5-login-config-file 618 krb-realm 617 location 617 password 617 peer-location 617 prompt 617 request-action 617 request-data 617 target 617 target adapter 617 targets 617 user-name 617 use-subject-credentials 618 Terminal mode 550 Terminal put 552 Terminal SCP adapter Process inputs - Get adapter name 562 allow unknown hosts 563 establish-connection-timeout-secs 564 host name 563 known hosts config 563 local file 562 password 563 password encryption type 563 port 563 preferred pk algorithm 564 remote file 562 target 562 user name 563 Process inputs - put adapter name 564 allow unknown hosts 565 establish-connection-timeout-secs 566 host name 565 known hosts config 565 local file 564 password 565 password encryption type 565 port 565 preferred pk algorithm 566 remote file 564 target 564 user name 565 Process outputs - Get adapter response 564 Process outputs - put adapter response 566 Terminal SFTP cd 566 lcd 580 Terminal SFTP adapter Process inputs - cd adapter name 567 allow unknown hosts 568 character-set 568 directory 568 establish-connection-timeout-secs 568 host name 567 known hosts config 567 password 567

674

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
password encryption type 567 port 567 preferred pk algorithm 568 target 567 user name 567 Process inputs - chgrp adapter name 569 allow unknown hosts 570 character-set 570 establish-connection-timeout-secs 570 file name 570 group id 570 host name 569 known hosts config 569 password 569 password encryption type 569 port 569 preferred pk algorithm 570 target 569 user name 569 Process inputs - chmod adapter name 571 allow unknown hosts 572 character-set 572 establish-connection-timeout-secs 572 file name 572 host name 571 known hosts config 572 password 571 password encryption type 571 permissions 572 port 571 preferred pk algorithm 572 target 571 user name 571 Process inputs - chown adapter name 573 allow unknown hosts 574 character-set 575 establish-connection-timeout-secs 575 file name 574 host name 573 known hosts config 574 password 573 password encryption type 574 port 573 preferred pk algorithm 574 target 573 user id 574 user name 573 Process inputs - get adapter name 578 allow unknown hosts 579 character-set 579 establish-connection-timeout-secs 579 host name 578 known hosts config 579 local file 579 password 578 password encryption type 578 port 578 preferred pk algorithm 579 remote file 579 target 578 user name 578 Process inputs - get-dir adapter name 575 allow unknown host 577 character-set 577 establish-connection-timeout-secs 577 host name 576 known hosts config 576 local directory 576 password 576 password encryption type 576 port 576 preferred pk algorithm 577 remote directory 577 target 575 user name 576 Process inputs - lcd adapter name 580 allow unknown hosts 581 character-set 581 directory 581 establish-connection-timeout-secs 581 host name 580 known hosts config 581 password 580 password encryption type 581 port 580 preferred pk algorithm 581 target 580 user name 580 Process inputs - lpwd adapter name 582 allow unknown hosts 583 character-set 583 establish-connection-timeout-secs 583 host name 582 known hosts config 583 password 582 password encryption type 583 port 582 preferred pk algorithm 583 target 582 user name 582 Process inputs - ls adapter name 584 allow unknown hosts 585 character-set 585 directory 585 establish-connection-timeout-secs 585 host name 584

Index

675

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
known hosts config 585 password 584 password encryption type 585 port 584 preferred pk algorithm 585 target 584 user name 584 Process inputs - mkdir adapter name 586 allow unknown hosts 587 character-set 587 directory 587 establish-connection-timeout-secs 587 host name 586 known hosts config 587 password 586 password encryption type 587 port 586 preferred pk algorithm 587 target 586 user name 586 Process inputs - mkdirs adapter name 588 allow unknown hosts 589 character-set 589 directory 589 establish-connection-timeout-secs 589 host name 588 known hosts config 589 password 588 password encryption type 589 port 588 preferred pk algorithm 589 target 588 user name 588 Process inputs - put adapter name 592 allow unknown hosts 593 character-set 594 establish-connection-timeout-secs 594 host name 592 known hosts config 593 local file 594 password 593 password encryption type 593 port 593 preferred pk algorithm 593 remote file 594 target 592 user name 593 Process inputs - put dir adapter name 590 allow unknown hosts 591 character-set 592 establish-connection-timeout-secs 592 host name 590 known hosts config 591 local directory 590 password 591 password encryption type 591 port 590 preferred pk algorithm 591 remote directory 591 target 590 user name 590 Process inputs - pwd adapter name 595 allow unknown hosts 596 character-set 596 establish-connection-timeout-secs 596 host name 595 known hosts config 595 password 595 password encryption type 595 port 595 preferred pk algorithm 596 target 595 user name 595 Process inputs - rename adapter name 597 allow unknown hosts 598 character-set 598 establish-connection-timeout-secs 598 host name 597 known hosts config 597 new file 598 old file 598 password 597 password encryption type 597 port 597 preferred pk algorithm 598 target 597 user name 597 Process inputs - rm adapter name 599 allow unknown hosts 600 character-set 600 establish-connection-timeout-secs 600 file name 600 host name 599 known hosts config 600 password 599 password encryption type 599 port 599 preferred pk algorithm 600 target 599 user name 599 Process inputs - symlink adapter name 601 allow unknown hosts 602 character-set 603 establish-connection-timeout-secs 603 file name 602 host name 601

676

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
known hosts config 602 link 602 password 601 password encryption type 602 port 601 preferred pk algorithm 602 target 601 user name 601 Process outputs - cd adapter response 568 Process outputs - chgrp adapter response 570 Process outputs - chmod adapter response 573 Process outputs - chown adapter response 575 Process outputs - get adapter response 580 Process outputs - get-dir adapter response 577 Process outputs - lcd adapter response 582 Process outputs - lpwd adapter response 584 Process outputs - ls adapter response 586 Process outputs - mkdir adapter response 588 Process outputs - mkdirs adapter response 590 Process outputs - put adapter response 594 Process outputs - put dir adapter response 592 Process outputs - pwd adapter response 596 Process outputs - rename adapter response 598 Process outputs - rm adapter response 601 Process outputs - symlink adapter response 603 Terminal SSH adapter Process inputs adapter name 605 allow unknown hosts 606 character-set 607 command 606 command encryption type 607 command timeout 607 commands 606 connection name 605 establish-connection-timeout-secs 607 host name 605 known hosts config 606 password 605 password encryption type 605 port 605 preferred PK algorithm 606 prompt 607 prompts 607 target 605 terminate connection 606 user name 605 Process outputs adapter response 607 Terminal Telnet adapter Process inputs adapter name 619 character-set 621 command 620 command encryption type 620 command timeout 620 commands 620 connection name 620 host name 619 login prompt 619 password 619 password encryption type 619 password prompt 619 port 619 prompt 621 prompts 621 target 619 terminate connection 620 user name 619 Process outputs adapter response 621 Terminal Windows Command adapter Process inputs adapter name 621 command 621 command timeout 622 host name 622 password 622 user name 622 Process outputs adapter response 622

U
Update 531

W
Web 622 Web Services adapter clear-asynchronous-cache 438 HTTPS Client Authentication 446 Process inputs - Make SOAP request method one truststore file 623 SSL Authentication 445

Index

677

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Web Services adapter configuration alias 441 certificate-data 441 certificate-file 440 created-validation 439 delay 438 host 441, 453, 457, 462 keystore-file 441 keystore-password 441 nonce-validation 439 password 439, 441, 442, 453, 457, 462 password-type 439 port 441, 453, 457, 462 private-key-data 440 private-key-file 440 proxy-settings 441 signature-properties 440 sign-request 439 sign-timestamp 440 sign-username-token 440 timestamp 438 time-to-live 438 user-name 439, 442, 453, 457, 462 username-token 438 Web Services adapter request with JAX WS approach in Message mode alias 462 allow-unsigned-certificate 459 certificate-data 461 certificate-file 461 client-alias 460 created-validation 460 endpoint-address 459 install-certificate 459 invocation-mode 462 keystore-file 459, 462 keystore-passphrase 459 keystore-password 462 nonce-validation 460 passphrase 459 password 460, 462 password encryption type 460 password type 460 port-name 459 private-key-data 461 private-key-file 461 service-name 459 signature-properties 461 sign-request 460 sign-timestamp 461 sign-username-token 461 soap-action 459 soap-message 459 timestamp 460 time-to-live 460 truststore-file 459 user-name 460 username-token 460 use-ssl-certificate 459 wsdl-location 459 Web Services adapter request with JAX WS approach in Payload mode authentication 456 invocation-mode 457 password 456 password encryption type 457 password type 457 port-name 456 service-name 456 soap-action 456 soap-body-content 456 user-name 456 wsdl-location 456 Web Services adapter request with Method one approach allow-unsigned-certificate 447 client-alias 447 Content-Type 447 http-connection-properties 447 install-certificate 447 keystore-file 447 keystore-passphrase 447 ntlm authentication 447 passphrase 447 password 447 soap-body-content 447 soap-message 447 soap-url 447 transport 447 truststore-file 447 user-name 447 use-ssl-certificate 447 Web Services adapter request with Method two approach chunked-encoding 453 connection 453 name 453 password 452 proxy-settings 453, 457, 462 soap-action 452 soap-body-content 453 soap-header-content 453 soap-url 452 soap-version 452, 459 terminate-on-exit 453 user-name 452 Web Services adapter response with JAX WS approach in Poll Asynchronous mode request-name 467 Windows Command adapter 312 configuration 314 request elements 318 setting permissions 313 Windows Command adapter configuration config 314 logon-with-user-credentials 315

678

BMC Atrium Orchestrator Base Adapters User Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
escape-double-quotes 315 executable 315 executable-directory 315 max-request-queue-size 316 password 315 protocol 315 script-file-path 316 target 314 user-name 315 Windows Command adapter request command 318 commands 318 host 318 password 318 target 318 targets 318 user-name 318 Windows Command adapter response command 322 command-output 322 commands-output 322 error 321, 322 execution-milliseconds 322 exit-code 322 line 322 line-count 322 metadata 322 os-id 321 os-version 321 output 322 request-metadata 321 status 321, 322 target-metadata 321 target-output 321 targets-output 321 workflow 14 Write 538 FTP adapter with put command 194 FTP adapter with pwd command 197 FTP adapter with rename command 200, 201 FTP adapter with rm command 203, 204 FTP adapter with rmdir command 206, 207 FTP adapter with stat command 210 Kerberized SSH adapter with local client 131, 135 Kerberized SSH for Java client 125 SCP adapter with get action 156, 157 SCP adapter with put action 161 SFTP adapter with cd command 224 SFTP adapter with chgrp command 229 SFTP adapter with chmod command 232, 234 SFTP adapter with chown command 239 SFTP adapter with get command 244 SFTP adapter with get-dir command 249 SFTP adapter with lcd command 254, 256 SFTP adapter with lpwd command 257, 259, 261 SFTP adapter with ls command 264, 267 SFTP adapter with mkdir command 270 SFTP adapter with mkdir commands 270 SFTP adapter with mkdirs command 275, 277 SFTP adapter with put command 280 SFTP adapter with put-dir command 285 SFTP adapter with rename command 295 SFTP adapter with rm command 300 SFTP adapter with symlink command 305 SSH adapter with KBI 115 Windows Command adapter 319 xml sample response command line adapter 67 file adapter with read action 49 file adapter with write action 56 FTP adapter with append command 172 FTP adapter with cd command 175 FTP adapter with cdup command 178 FTP adapter with get command 182 FTP adapter with mkdir command 189 FTP adapter with mode command 192 FTP adapter with put command 196 FTP adapter with pwd command 199 FTP adapter with rename command 202 FTP adapter with rm command 205 FTP adapter with stat command 212 Kerberized SSH adapter with local client 137 SCP adapter 157 SCP adapter with put action 163 SFTP adapter with chgrp command 231 SFTP adapter with chmod command 235 SFTP adapter with chown command 241 SFTP adapter with get command 246 SFTP adapter with get-dir command 251 SFTP adapter with mkdir command 272 SFTP adapter with put command 282 SFTP adapter with put-dir command 287 SFTP adapter with rename command 297 SFTP adapter with symlink command 306, 307

X
XML response for Adapter 334 xml sample request command line adapter on UNIX 62 file adapter with append action 56, 57, 58 file adapter with delete action 58 file adapter with read action 47 file adapter with read action, header 53 file adapter with read action, no header 52 file adapter with write action 53 FTP adapter with append command 170 FTP adapter with cd command 173, 174 FTP adapter with cdup command 176, 177 FTP adapter with get command 180 FTP adapter with ls command 183 FTP adapter with mkdir command 187, 188 FTP adapter with mode command 190, 191

Index

679

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
SSH adapter with rmdir command 209

680

BMC Atrium Orchestrator Base Adapters User Guide

Notes

*991571* *991571* *991571* *991571*

*175199*