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. The PowerShell actor adapter works with PowerShell 1.0 and 2.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.

To override the configuration properties in the adapter configuration, include the target, user name, and password elements in the request. The following table describes the elements of the PowerShell adapter request.

Elements of the PowerShell adapter request

Element	Definition	Required
`<targets>`	Contains the `<target>` elements	No
`<target>`	Used to reference a target in the request If the target element is not defined, the default target in the adapter configuration is used.	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 computer You must have administrative roles and privileges on the remote host computer. Your environment determines whether this element is required.	Conditional; required to define a dynamic target computer
`<password>`	Contains the password corresponding to the specified user name for authentication on the remote host computer Your environment determines whether this element is required. Valid values: Base64, Plain (default) Note: This element can contain an `encryption-type` attribute to indicate whether the password provided is encrypted. You can provide special characters in the password such as $, *, &, {, }, and so on.	Conditional; required to define a dynamic target computer
`<powershell-version>`	Specifies the version of Microsoft Windows PowerShell on which the command is to be executed Valid values: 1.0, 2.0, 3.0, 4.0	No
`<powershell-consolefile>`	Specifies the PowerShell console file to be loaded	No
`<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
`<use-userprofile>`	Determines whether the user profile is to be loaded Valid values: true, false	No
`<commands>`	Contains a single or multiple command elements	Yes
`<command>`	Contains the PowerShell command to be executed	Yes
`<enable-psremoting>`	Specifies whether to enable the remoting feature of PowerShell version 2.0 Valid values: true, false (default) Note For the remoting feature to work: You must set `<powershell-version>` to 2.0. PowerShell version 2.0 must be installed on the peer on which the adapter is enabled. For more information about PowerShell remoting, go to http://blogs.msdn.com/b/powershell/archive/2009/01/06/manage-winrm-settings-with-wsman-provider.aspx The target referenced in `<target>` must also have PowerShell version 2.0 installed on it and the remoting feature must be configured on this target. If you specify `<enable-psremoting>` in the adapter configuration and an adapter request, the values in the request override the values in the configuration.	No
`<logon-with-user-credentials>`	Starts a service on the remote computer Set `<logon-with-user-credentials>` to true to start the remote service using the credentials specified in the adapter configuration. Set `<logon-with-user-credentials>` to false, to start the remote service using the SYSTEM credentials on the remote server. Valid values: true, false (default) Note To start a service on the remote computer, you must set the rights for the user name specified in `<user-name>` to Log on as a service. Use the Microsoft Windows Local Security Policy tool to set the user name rights.	No
`<impersonate-user>`	Specifies whether to enable the user impersonation and allow the specified user to execute tasks by using the security context of another user (For example, BAO service running under a user account) For example, a service running as LocalSystem could access network resources by impersonating a specific user account. This account would have been configured with the necessary permissions to access a network resource, something the service would not be able to do otherwise.For more information about how user impersonation works, see Impersonation If set to true, the Service Control Manager (SCM) API is invoked with the user specified in the adapter request or configuration. By default, the xCmd utility runs under the security context of the BAO service running under a user account. When we specify `<impersonate-user>` as true, the SCM API is invoked with the user specified in the adapter request or configuration. Valid values: true, false (default)	No
`<service-launch-mode>`	Specifies the mode to launch the xCommand service on a remote system By default, the xCommand utility is launched on 32-bit mode. Valid value: 64bit Specify 64bit only if you want to launch the xCommand service on a 64-bit image mode on the target system. BMC recommends that you do not specify any value if 64-bit is not required as it can affect the time taken for the request to execute.	No
`<redirect-error-to-success-output-stream>`	Specifies whether to redirect the command output error stream to the success output stream Valid values: true, false (default) When specified as true, all PowerShell commands are redirected to the success output stream. The PowerShell adapter uses the xCMD utility to connect to the Windows System remotely to perform PowerShell commands. Since the xCMD utility only consumes output streams, it fails to process the data written on error streams and the actual output is not processed by the xCMD utility and reports an error. This problem occurs while executing the PowerShell Module cmd-lets version 3.0 and later.	No

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

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 BMC Atrium Orchestrator 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-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>

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 BMC Atrium Orchestrator 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 BMC Atrium Orchestrator 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>
          <powershell-version>2.0</powershell-version>
          <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>
       <powershell-version>1.0</powershell-version>
       <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>

Adapter request and response for the PowerShell adapter

Comments