Adapter request and response for the Windows Command adapter

The Windows Command adapter does not use an 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 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 use a context item as an input for an adapter request, you must enclose the adapter request in <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <adapterName-adapter-request> element.

BMC recommends that you do not include empty elements in the adapter request because they might cause errors.

Notes

The Windows Command adapter supports executing VBScript and batch scripts on a host computer.
To execute scripts that are available on a CDP or a peer, you must set <script-file-path> to "local" in the adapter configuration. If <script-file-path> is set to "local", the copied script file is deleted automatically after it executes on the target computer.
To execute scripts that are available on a remote computer, you must set <script-file-path> to "remote" in the adapter configuration.

The following table describes the elements for the Windows Command adapter request:

Elements of the Windows Command adapter request

Element	Description	Required
`<targets>`	Contains the `<target>` elements	Conditional; required if a target is referenced or defined in the request
`<target>`	Contains the `name` attribute that references a configuration node from the adapter configuration, or contains the elements that define a dynamic target computer If you do not provide the value, the default target in the adapter configuration is used.	Conditional; 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 applies to a dynamic target.	Conditional; 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.	Conditional; required based on your environment
`<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 `<password>` element can contain an `encryption-type` attribute that indicates whether the password specified is encrypted. Valid values for `encryption-type`: Base64, Plain (default)	Conditional; required based on your environment
`<character-set>`	Specifies the supporting CharSet Also called character set, it includes identifiers describing a series of universal characters. Note The locale and character set of the target computer must be compatible with the character set provided in the `<character-set>` element to get the desired results.	No
`<commands>`	Contains the `<command>` elements	Yes
`<command>`	Specifies the commands to be executed on the remote host The `<command>` element can contain the following attributes: `working-dir`: Specifies the location of the folder where the command is to be executed. `timeout-secs`: Specifies 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. If a command is not executed in the time specified in `timeout-secs`, an error message is returned. If `<script-file-path>` is set to "local" in the adapter configuration, the copied command script is deleted if the value of `timeout-secs` turns zero before the command completes. Notes Commands can include a space-separated list of parameters. If the name of the script file has spaces, the script file name and the path must be enclosed in double quotation marks (" "). A relative path must start with .\ (dot and back slash characters). If a command contains parameters with spaces, the parameters must be enclosed in double quotation marks (" "). Examples: Command with parameters without spaces `<command>C:\scripts\mycommand.bat arg1 arg2</command>` Command with parameters with spaces `<command>"C:\My Scripts Folder\mycommand.bat" "C:\my data1" "C:\my data2"</command>`	Yes

The following figure shows an XML template of the adapter request for the Windows Command adapter.

XML template of the Windows Command adapter request

<windows-command-request>
   <targets>
     <target name=""/>
     <target>
       <host></host>
       <user-name></user-name>
       <password encryption-type=""></password>
       <character-set></character-set>
      </target>
   </targets>
   <commands>
     <command></command>
     <command></command>
     <command></command>
   </commands>
</windows-command-request>

Note

If the command length is more than 1000 characters, save the command text as a script file. Provide the complete path and the name of the script file as the value for the <command> element in the adapter request.

For example,
<commands>
<command working-dir="C:\temp1\with space">C:\abc\OSProperties.ps1</command>
</commands>

The following figure shows an XML sample of the Windows Command adapter request when the first target references the adapter configuration and the second target is a dynamic target.

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 encryption-type-"Plain">test</password>
       <character-set>gb18030</character-set>
     </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.

The following figure 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.

XML sample of the Windows Command with systeminfo command

<windows-command-request>
 <targets>
  <target>
   <host>server3</host>
   <user-name>user</user-name>
   <password encryption-type="Plain">test</password>
   <character-set>gb18030</character-set>
  </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. The <script-file-path> element must be set to "remote" in the adapter configuration if you want to specify a relative path in the command. The following figure shows an XML sample of the Windows Command adapter request to execute a batch script using a relative path.

XML sample of the Windows Command adapter request to execute a batch script using a relative path

<windows-command-request>
<commands>
  <command working-dir=" D:\scripts">.\SampleScript.bat</command>
  <command working-dir=" D:\scripts">.\OSProperties.bat</command>
</commands>
</windows-command-request>

Notes

If you do not specify the working-dir attribute in the <command> element and <script-file-path> is "local" in the adapter configuration, the command script is copied and executed on the \\target-IP\Admin$ folder on the remote computer. After the command script executes successfully on the remote computer, it is deleted.
If you do not specify the working-dir attribute in the <command> element and <script-file-path> is "remote" in the adapter configuration, the command executes on the c:\windows\system32 folder on the remote computer.
If you specify the working-dir attribute in the <command> element and <script-file-path> is "local" in the adapter configuration, the command script is copied and executed on the specified working directory on the remote computer. After the command script executes successfully on the remote computer, it is deleted.
If you specify the working-dir attribute in the <command> element and <script-file-path> is "remote" in the adapter configuration, the script executes on the specified working directory on the remote computer provided it already exists in the directory. If the script does not exist on the remote computer, an error message is returned.

The following figure shows an XML sample of the Windows Command adapter request to execute a batch script (without parameters) using a complete path.

XML sample of the Windows Command adapter request to execute a batch script using a complete path

<windows-command-request>
  <targets>
    <target>
      <host>10.128.249.47</host>
      <userName>admin</userName>
      <password>bmcadmin</password>
    </target>
  </targets>
  <commands>
    <command timeout-secs="60">"D:\scripts\test.bat"</command>
  </commands>
</windows-command-request>

The following figure shows an XML sample of the adapter request for the Windows Command adapter for executing batch commands with parameters.

XML sample of the Windows Command adapter request with script execution using batch commands with parameters

<windows-command-request>
      <targets>
        <target>
        <host>10.128.249.47</host>
          <userName>admin</userName>
          <password>bmcadmin</password>
        </target>
      </targets>
      <commands>
	      <command timeout-secs="60">"D:\scripts\test.bat" arg1 arg2</command>
      </commands>
</windows-command-request>

The following figure shows an XML sample of the Windows Command adapter request to execute a VBScript.

XML sample of the Windows Command adapter request to execute a VBScript

<windows-command-request>
  <targets>
    <target>
      <host>10.128.249.47</host>
      <userName>admin</userName>
      <password>pwdadmin</password>
    </target>
  </targets>
  <commands>
    <command timeout-secs="60">cscript "D:\scripts\test.vbs"</command>
  </commands>
</windows-command-request>

The Windows Command adapter returns an adapter response that contains the details for the command executed by the adapter request. The following table describes the elements of a Windows Command adapter response:

Elements of a Windows Command adapter response

Element	Description
`<request-metadata>`	Contains the request level summary information
`<status>`	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.
`<targets-output>`	Contains the command output for all target computers
`<target-output>`	Contains the command output for a specific target The `host` attribute provides the host name or the IP address of the target computer.
`<target-metadata>`	Contains the target level summary information
`<os-id>`	Indicates the system type for the target computer
`<os-version>`	Indicates the system version for the target computer
`<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>`	Contains the command response for a specific command
`<metadata>`	Contains the command summary information
`<command>`	Specifies the command executed
`<line-count>`	Specifies the number of lines returned by the command
`<execution-milliseconds>`	Specifies the duration of the command execution, in 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 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 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>`	Contains the lines that result from the command
`<line>`	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.

The following figure illustrates an XML sample of the adapter response for the Windows Command adapter using the default xCmd protocol.

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>
            <line index="12">   IP Address. . . . . . . . . . . . : 192.168.10.2</line>
            <line index="13">   Subnet Mask . . . . . . . . . . . : 255.255.252.0</line>
            <line index="14">   Default Gateway . . . . . . . . . : 192.168.1.1</line>
            <line index="15">Remote application exited with code: 0</line>
          </output>
        </command-output>
      </commands-output>
    </target-output>
  </targets-output>
</windows-command-output>

The following figure illustrates an XML sample of the adapter response for the Windows Command adapter using the SSH protocol.

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>

The following figure illustrates an XML sample of the adapter response for the Windows Command adapter with script execution.

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>

The following figure shows an XML sample of the Windows Command adapter response for executing a batch script.

XML sample of the Windows Command adapter response for executing a batch script

<windows-command-output>
  <metadata>
     <status>success</status>
  </metadata>
  <targets-output>
    <target-output host="10.128.249.47">
      <metadata>
        <os-id>Windows Server 2008</os-id>
        <os-version>6.1.7600</os-version>
        <status>success</status>
      </metadata>
      <commands-output>
        <command-output>
          <metadata>
            <command>"D:\scripts\test.bat" </command>
            <line-count>20</line-count>
            <execution-milliseconds>5501</execution-milliseconds>
            <exit-code>0</exit-code>
            <status>success</status>
          </metadata>
          <output>
             <line index="1">Copyright 2010 BMC Software Ltd, Version: 1.5  </line>
             <line index="2">Connecting to remote service...</line>
             <line index="3">Connected to remote host.</line>
             <line index="4">C:\Windows\system32&gt;ipconfig</line>
             <line index="5">Windows IP Configuration</line>
             <line index="6">Ethernet adapter Local Area Connection:</line>
             <line index="7">   Connection-specific DNS Suffix  . : bmc.com</line>
             <line index="8">   Link-local IPv6 Address . . . . . : fe80::5097:4c5e:2289:76dd%13</line>
             <line index="9">   IPv4 Address. . . . . . . . . . . : 10.128.249.47</line>
             <line index="10">   Subnet Mask . . . . . . . . . . . : 255.255.254.0</line>
             <line index="11">   Default Gateway . . . . . . . . . : 10.128.248.1</line>
             <line index="12">Tunnel adapter isatap.bmc.com:</line>
             <line index="13">   Media State . . . . . . . . . . . : Media disconnected</line>
             <line index="14">   Connection-specific DNS Suffix  . : bmc.com</line>
             <line index="15">Tunnel adapter Local Area Connection* 12:</line>
             <line index="16">   Connection-specific DNS Suffix  . : </line>
             <line index="17">   IPv6 Address. . . . . . . . . . . :  2001:0:5ef5:79fd:1ce1:3b55:f57f:6d0</line>
             <line index="18">   Link-local IPv6 Address . . . . . : fe80::1ce1:3b55:f57f:6d0%12</line>
             <line index="19">   Default Gateway . . . . . . . . . : ::</line>
             <line index="20">Remote application exited with code: 0 </line>
           </output>
         </command-output>
       </commands-output>
      </target-output>
   </targets-output>
</windows-command-output>

The following figure shows an XML sample of the adapter response for the Windows Command adapter for executing batch commands with parameters.

XML sample of the Windows Command adapter response using batch commands with parameters

<adapter-response>
  <execution-duration>16639</execution-duration>
  <status>success</status>
  <messageBase64></messageBase64>
  <data>
    <windows-command-output>
      <metadata>
        <status>success</status>
      </metadata>
      <targets-output>
        <target-output host="10.128.249.47">
          <metadata>
            <os-id>Windows Server 2008</os-id>
            <os-version>6.1.7600</os-version>
            <status>success</status>
          </metadata>
          <commands-output>
            <command-output>
              <metadata>
                <command>"D:\scripts\test.bat" ram</command>
                <line-count>5</line-count>
                <execution-milliseconds>5507</execution-milliseconds>
                <exit-code>0</exit-code>
                <status>success</status>
              </metadata>
              <output>
                <line index="1">Copyright 2010 BMC Software Ltd, Version: 1.5  </line>
                <line index="2">Connecting to remote service...</line>
                <line index="3">Connected to remote host.</line>
                <line index="4">hello ram testing batch file with 1 argument</line>
                <line index="5">Remote application exited with code: 0 </line>
              </output>
            </command-output>
          </commands-output>
        </target-output>
      </targets-output>
    </windows-command-output>
  </data>
</adapter-response>

The following figure shows an XML sample of the adapter response for the Windows Command adapter request for script execution using VBScript.

XML sample of the Windows Command adapter response for script execution using VBScript

<adapter-response>
  <execution-duration>16459</execution-duration>
  <status>success</status>
  <messageBase64></messageBase64>
  <data>
    <windows-command-output>
      <metadata>
        <status>success</status>
      </metadata>
      <targets-output>
        <target-output host="10.128.249.47">
          <metadata>
            <os-id>Windows Server 2008</os-id>
            <os-version>6.1.7600</os-version>
            <status>success</status>
          </metadata>
          <commands-output>
            <command-output>
              <metadata>
                <command>cscript "D:\scripts\test.vbs"</command>
                <line-count>7</line-count>
                <execution-milliseconds>5488</execution-milliseconds>
                <exit-code>0</exit-code>
                <status>success</status>
              </metadata>
              <output>
                <line index="1">Copyright 2010 BMC Software Ltd, Version: 1.5  </line>
                <line index="2">Connecting to remote service...</line>
                <line index="3">Connected to remote host.</line>
                <line index="4">Microsoft (R) Windows Script Host Version 5.8</line>
                <line index="5">Copyright (C) Microsoft Corporation. All rights reserved.</line>
                <line index="6"> hello testing vb script </line>
                <line index="7">Remote application exited with code: 0 </line>
              </output>
            </command-output>
          </commands-output>
        </target-output>
      </targets-output>
    </windows-command-output>
  </data>
</adapter-response>

Page tree

Adapter request and response for the Windows Command adapter