Adapter request and response for the PowerShell adapter

The PowerShell actor adapter sends commands to PowerShell and receives responses and results from the CLI of PowerShell. 

Notes

  • 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. 
  • To override the configuration properties in the adapter configuration, include the target, user name, and password elements in the request.
  • You can specify <enable-psremoting> and <enable-psremoting-session> elements to run a list of multiple commands on a remote session. Only commands that are executed independently and do not return a PowerShell prompt are supported by the adapter. For more information, see Multiple-commands-in-a-remote-session.

The following table describes the elements of the PowerShell adapter request.

 Elements of the PowerShell adapter request

The following figure shows an XML sample for the PowerShell actor adapter request. 

XML sample of the PowerShell adapter request

<powershell-request>
  <targets>
   <target>
     <host></host>
     <user-name></user-name>
     <password encryption-type="">testpass</password>
     <character-set>gb18030</character-set>
     <powershell-consolefile>pshell.psc1</powershell-consolefile>
     <use-userprofile>true</use-userprofile>
   </target>
  </targets>
 <commands>
   <command></command>
   <command></command>
 </commands>
</powershell-request>

The following figure shows a sample adapter request when <enable-psremoting-session> is enabled and persistent connectivity is enabled.

<powershell-request>
   <targets>
     <target>
        <host>xxx.yyyy.bmc.com</host>
        <userName>Admin</userName>
        <password>AdminPass</password>
        <enable-psremoting-session>true</enable-psremoting-session>
        <enable-psremoting>true</enable-psremoting>
        <connection-name>PSConnection1</connection-name>
        <connection-ttl>500</connection-ttl>
        <terminate-on-exit>false</terminate-on-exit>
     </target>
    </targets>
    <commands>
        <command><![CDATA[hostname]]></command>
        <command continue-on-failure="false"><![CDATA[whoami]]></command>
        <command continue-on-failure="true" ignore-exit-code="true"><![CDATA[$mySessionVariable = 'This is my test for variable in session' ]]></command>
        <command ignore-exit-code="false">write-output $mySessionVariable</command>
    </commands>
</powershell-request>

The following figure shows the adapter response when <connection-name> is specified and adapter establishes the connection on Remote Target system and the session is captured successfully and commands are executed:

<powershell-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="xxx.yyyy.bmc.com">
     <metadata>
       <status>success</status>
     </metadata>
     <commands-output>
 <command-output>
         <metadata>
           <command>hostname</command>
           <line-count>1</line-count>
           <execution-milliseconds>126</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">xxx.yyyy.bmc.com</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>whoami</command>
           <line-count>1</line-count>
           <execution-milliseconds>156</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">xxx.yyyy.bmc.com\Admin</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>$mySessionVariable = 'This is my test for variable in session' </command>
           <line-count>1</line-count>
           <execution-milliseconds>31</execution-milliseconds>
           <exit-code>9999</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>write-output $mySessionVariable</command>
           <line-count>1</line-count>
           <execution-milliseconds>31</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">This is my test for variable in session</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</powershell-output>


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 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 TrueSight Orchestration Development Studio.

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>

The following figure shows an example of the Powershell adapter request with the get-service PowerShell command.
XML sample of the PowerShell adapter request with get-service command

<powershell-request>
  <targets>
   <target>
     <host>computer2</host>
     <user-name>testuser</user-name>
     <password encryption-type="Plain">testpass</password>
     <character-set>gb18030</character-set>
     <powershell-consolefile>pshell.psc1</powershell-consolefile>
     <use-userprofile>true</use-userprofile>
   </target>
  </targets>
  <commands>
   <command>get-service</command>
  </commands>
</powershell-request>

The following figure 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 TrueSight Orchestration Development Studio.
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>

The following figure 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 TrueSight Orchestration Development Studio.

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>

The following figure shows an XML sample for the PowerShell actor adapter request when the remoting feature is enabled.
XML sample of the PowerShell adapter request when the remoting feature is enabled

<powershell-request>
       <targets>
         <target>
         <host>10.128.249.47</host>
         <user-name>bmcadmin</user-name>
         <password encryption-type="Plain">Global@123</password>
         <enable-psremoting>true</enable-psremoting>
       </target>
       </targets>
         <commands>
            <command>ipconfig</command>
             .
             .
             .
         </commands>
</powershell-request>

The following figure shows an XML sample for the PowerShell actor adapter request when <logon-with-user-credentials> is set to true.

XML sample of the PowerShell adapter request when <logon-with-user-credentials> is set to true

<powershell-request>
 <targets>
    <target>
      <host>BMC-GLOBALLOGIC</host>
      <user-name>bmcadmin</user-name>
      <password>bmc123</password>
      <logon-with-user-credentials>true</logon-with-user-credentials>
   </target>
 </targets>
 <commands>
    <command>ipconfig</command>
 </commands>
</powershell-request> 

The PowerShell adapter response contains the result returned from an adapter request. The following figure shows an XML sample for the PowerShell adapter response with get-service PowerShell command.

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>

The following figure shows an XML sample for the PowerShell adapter response when the remoting feature is enabled in the adapter request.

XML sample of the PowerShell adapter response when the remoting feature is enabled

<powershell-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
  <target-output host="10.128.249.47">
   <metadata>
    <os-id>Windows XP</os-id>
    <os-version>5.1.2600</os-version>
    <status>success</status>
   </metadata>
   <commands-output>
    <command-output>
     <metadata>
      <command>ipconfig</command>
      <line-count>11</line-count>
      <execution-milliseconds>1492</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"> Connection-specific DNS Suffix . : bmc.com</line>
     <line index="4"> IP Address. . . . . . . . . . . . : 10.128.249.47</line>
     <line index="5"> Subnet Mask . . . . . . . . . . . : 255.255.254.0</line>
     <line index="6"> Default Gateway . . . . . . . . . : 10.128.248.1</line>
     <line index="7">Ethernet adapter...........:</line>
     <line index="8"> Connection-specific DNS Suffix . : </line>
     <line index="9"> IP Address. . . . . . . . . . . . : 0.0.0.0</line>
     <line index="10"> Subnet Mask . . . . . . . . . . . : 0.0.0.0</line>
     <line index="11"> Default Gateway . . . . . . . . . : </line>
    </output>
   </command-output>
  </commands-output>
 </target-output>
</targets-output>
</powershell-output>

The following figure shows an XML sample for the PowerShell actor adapter response when <logon-with-user-credentials> is set to true.

XML sample of the PowerShell adapter response when <logon-with-user-credentials> is set to true

<powershell-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="10.128.249.47">
     <metadata>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ipconfig</command>
           <line-count>15</line-count>
           <execution-milliseconds>32938</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">Windows IP Configuration</line>
           <line index="5">Ethernet adapter Local Area Connection:</line>
           <line index="6"> Connection-specific DNS Suffix . : bmc.com</line>
           <line index="7"> IP Address. . . . . . . . . . . . : 10.128.249.47</line>
           <line index="8"> Subnet Mask . . . . . . . . . . . : 255.255.254.0</line>
           <line index="9"> Default Gateway . . . . . . . . . : 10.128.248.1</line>
           <line index="10">Ethernet adapter {EDE30461-C964-4723-863B-AD7D4CFE4886}:</line>
           <line index="11"> Connection-specific DNS Suffix . : </line>
           <line index="12"> IP Address. . . . . . . . . . . . : 0.0.0.0</line>
           <line index="13"> Subnet Mask . . . . . . . . . . . : 0.0.0.0</line>
           <line index="14"> Default Gateway . . . . . . . . . : </line>
           <line index="15">Remote application exited with code: 0 </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</powershell-output> 

The following figure shows an XML sample for the PowerShell actor adapter request when the <impersonate-user> is set to true.

XML sample for the PowerShell actor adapter request when the <impersonate-user> is set to true

<powershell-request>
   <targets>
     <target>
       <host>vm-w23-rds87</host>
       <userName>Domain_Name\User</userName>
       <password encryption-type="Plain">XXXXXXX</password>
       <impersonate-user>true</impersonate-user>
       <logon-with-user-credentials />
       <service-launch-mode />
       <character-set />
       <powershell-version>1.0</powershell-version>
     </target>
   </targets>
   <commands>
     <command>get-service</command>
   </commands>
</powershell-request>

The following figure shows an XML sample for the PowerShell actor adapter request when the <service-launch-mode> is 64-bit.

XML sample for the PowerShell actor adapter request when the <service-launch-mode> is 64-bit

<powershell-request>
   <targets>
     <target>
       <host>vm-w23-rds87</host>
       <userName>Domain_Name\User</userName>
       <password encryption-type="Plain">XXXXXXX</password>
       <impersonate-user>true</impersonate-user>
       <logon-with-user-credentials />
       <service-launch-mode>64bit</service-launch-mode>
       <character-set />
       <powershell-version>1.0</powershell-version>
     </target>
   </targets>
   <commands>
     <command timeout-secs="150">whoami</command>
   </commands>
 </powershell-request>

The following figure shows an XML sample for the PowerShell actor adapter request when the <enable-psremoting-session> is true. 

XML sample for the PowerShell actor adapter request when the <enable-psremoting-session> is true

<powershell-request>
     <targets>
       <target>
        <host>clm-XXXX-zzzzz.bmc.com</host>
        <userName>Admin</userName>
        <password>password</password>
        <enable-psremoting-session>true</enable-psremoting-session>
        <enable-psremoting>true</enable-psremoting>
        </target>
     </targets>
     <commands>
       <command><![CDATA[hostname]]></command>
       <command continue-on-failure="false"><![CDATA[whoami]]></command>
       <command continue-on-failure="true" ignore-exit-code="true"><![CDATA[$mytable = 'This is my test for variable in session' ]]></command>
      <command ignore-exit-code="false">write-output $mytable</command>
    </commands>
</powershell-request>

The following figure shows the sample adapter response for the request when the <enable-psremoting-session> is true.

Adapter response for the request when the <enable-psremoting-session> is true

<powershell-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-XXXX-zzzzz.bmc.com">
     <metadata>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>hostname</command>
           <line-count>1</line-count>
           <execution-milliseconds>214</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">clm-XXXX-zzzzz</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>whoami</command>
           <line-count>1</line-count>
           <execution-milliseconds>235</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">clm-XXXX-zzzzz\administrator</line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>$mytable = 'This is my test for variable in session' </command>
           <line-count>1</line-count>
           <execution-milliseconds>237</execution-milliseconds>
           <exit-code>9999</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
         </output>
       </command-output>
       <command-output>
         <metadata>
           <command>write-output $mytable</command>
           <line-count>1</line-count>
           <execution-milliseconds>523</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">This is my test for variable in session</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</powershell-output>

The following figure shows the adapter response when the <enable-psremoting-session> is true but the adapter is unable to connect to a remote server. 

Adapter response when the <enable-psremoting-session> is true but the adapter is unable to connect to a remote server 

<powershell-output>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-XXXX-zzzzz.bmc.com">
     <metadata>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>$s = Enter-PSSession -ComputerName clm-XXXX-zzzzz.bmc.com -credential $cred</command>
           <line-count>11</line-count>
           <execution-milliseconds>17953</execution-milliseconds>
           <exit-code>1</exit-code>
           <status>error</status>
           <error>Exit code indicates error</error>
         </metadata>
         <output>
           <line index="1">Enter-PSSession : Connecting to remote server clm-XXXX-zzzzz.bmc.com failed </line>
           <line index="2">with the following error message : Access is denied. For more information, see </line>
           <line index="3">the about_Remote_Troubleshooting Help topic.</line>
           <line index="4">At line:1 char:6</line>
           <line index="5">+ $s = Enter-PSSession -ComputerName clm-XXXX-zzzzz.bmc.com -credential </line>
           <line index="6">$cred;echo ...</line>
           <line index="7">+      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</line>
           <line index="8">    + CategoryInfo          : InvalidArgument: (clm-XXXX-zzzzz.bmc.com:String) </line>
           <line index="9">    [Enter-PSSession], PSRemotingTransportException</line>
           <line index="10">    + FullyQualifiedErrorId : CreateRemoteRunspaceFailed</line>
           <line index="11"> </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</powershell-output>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*