Agent management operations for Microsoft System Center Operations Manager 2012

This topic describes the adapter requests and responses for the Agent management operations and describes the elements used in the requests.

Approve Agent Pending Action operation

The Approve Agent Pending Action operation approves pending management actions. 

The following table shows the adapter request elements for the Approve Agent Pending Action operation

Adapter request elements for the Approve Agent Pending Action operation

ElementDefinitionRequired
<operation-name>Specifies the name of the operation: Approve-SCOMPendingManagementYes
<timeout-secs>Specifies the duration after which the operation times out 

Default value: 60 seconds
No
<command-parameters>Contains the elements required to execute the operationYes
<agent-pending-action>Specifies the parent element that contains the filter criterion
used to retrieve the agents that have actions in the pending state
Yes
<filters>Specifies the parent element that contains the search criterionNo
<filter>

Specifies the parent element for a single search criterion 

You can specify more than one filter criterion by using multiple <filter> elements.

Conditional;
required if the <filters> element is specified

<agent-pending-action-key>

Specifies the key that is used to locate an agent 

Valid values:

  • AgentName
  • ManagementServerName
  • AgentPendingActionType
  • ManagementGroup
  • ManagementGroupId

Conditional; required if the <filters> element is specified

<agent-pending-action-val>

Specifies the value of the key specified in the <agent-pending-action-key> element

Conditional; required if the <filters> element is specified

<operand>

Specifies the operation that is performed by using the values specified in the <agent-pending-action-key> and <agent-pending-action-val> elements 

Valid values:

  • equals
  • not equals
  • matches

Conditional; required if the <filters> element is specified

<preview>

Specifies whether you want to preview the results of the operation 

Valid values:

  • true: Indicates that you want to preview the results of the operation
  • false: Indicates that the operation is executed without displaying the results of the execution (default)

No

The following figure shows the <items> XML for the Approve Agent Pending Action operation.

<items> XML for the Approve Agent Pending Action operation

<items>
  <item>
  <operation-name>approve-SCOMPendingManagement</operation-name>
  <timeout-secs>120</timeout-secs>
  <command-parameters>
  <agent-pending-action>
  <filters>
	<filter>
		<agent-pending-action-key>AgentName</agent-pending-action-key>
		<agent-pending-action-val>abc.synapse.com</agent-pending-action-val>
		<operand>matches</operand>
	</filter>
  </filters>
  </agent-pending-action>
  <preview>true</preview>
  </command-parameters>
  </item>
</items>

The following figure shows the sample adapter request.

Sample adapter request XML for the Approve Agent Pending Action operation

<request-data>
  <scom-request>
    <operation-name>Approve-SCOMPendingManagement</operation-name>
    <command-request>
      <timeout-secs>220</timeout-secs>
      <command-parameters>
        <agent-pending-action>
          <filters>
            <filter>
              <agent-pending-action-key>AgentName</agent-pending-action-key>
              <agent-pending-action-val>VW-PUN-BNA-DV21.punbnadv21.local</agent-pending-action-val>
              <operand>equals</operand>
            </filter>
          </filters>
        </agent-pending-action>
        <preview>false</preview>
      </command-parameters>
    </command-request>
  </scom-request>
</request-data> 

The following figure shows the sample adapter response.

Adapter response for the Approve Agent Pending Action operation

<scom-response>
  <metadata>
    <status>success</status>
    <count>1</count>
  </metadata>
  <commands-output>
    <command-output>
      <metadata>
        <command> Import-Module OperationsManager; Approve-SCOMPendingManagement -pendingaction ((Get-SCOMPendingManagement) 
| where-object {$_.AgentName -eq 'VW-PUN-BNA-DV21.punbnadv21.local'}) | format-list</command>
        <execution-milliseconds>66910</execution-milliseconds>
        <exit-code>0</exit-code>
        <status>success</status>
        <count>0</count>
      </metadata>
      <output />
    </command-output>
  </commands-output>
</scom-response> 

Back to top 

Find Agent Pending Action operation

The Find Agent Pending Action operation retrieves the actions, which are pending with agents. You can filter the result by specifying a filter criterion. 

The following table shows the adapter request elements for the Find Agent Pending Action operation.

Adapter request elements for the Find Agent Pending Action operation

ElementDefinitionRequired
<operation-name>Specifies the name of the operation:
Get-SCOMPendingManagement
Yes

<command-parameters>

Specifies the parent element for the command parameters

Yes

<filters>

Specifies the parent element that contains the search criterion

No

<filter>

Specifies the parent element for a single search criterion 

You can specify more than one filter criterion by using multiple <filter> elements.

Conditional; required if the <filters> element is specified

<agent-pending-action-key>

Specifies the key that is used to locate an agent 

Valid values:

  • AgentName
  • ManagementServerName
  • AgentPendingActionType
  • ManagementGroup
  • ManagementGroupId

Conditional; required if the <filters> element is specified

<agent-pending-action-val>

Specifies the value of the key specified in the <agent-pending-action-key> element

Conditional; required if the <filters> element is specified

<operand>

Specifies the operation that is performed by using the values specified in the <agent-pending-action-key> and <agent-pending-action-val> elements 

Valid values:

  • equals
  • not equals
  • matches

Conditional; required if the <filters> element is specified

The following figure shows the <items> XML for the Find Agent Pending Action operation.

<items> XML for the Find Agent Pending Action operation

<items>
  <item>
  <operation-name>get-SCOMPendingManagement</operation-name>
  <timeout-secs>120</timeout-secs>
  <command-parameters>
    <filters>
     <filter>
      <agent-pending-action-key>AgentName</agent-pending-action-key>
      <agent-pending-action-val>abc.synapse.com</agent-pending-action-val>
      <operand>matches</operand>
     </filter>
    </filters>
  </command-parameters>
  </item>
</items>

The following figure shows the sample adapter request.

Sample adapter request XML for the Find Agent Pending Action operation

<request-data>
  <scom-request>
    <operation-name>Get-SCOMPendingManagement</operation-name>
    <command-request>
      <timeout-secs>120</timeout-secs>
      <command-parameters>
        <filters>
          <filter>
            <agent-pending-action-key>AgentPendingActionType</agent-pending-action-key>
            <agent-pending-action-val>RepairAgent</agent-pending-action-val>
            <operand>equals</operand>
          </filter>
          <filter>
            <agent-pending-action-key>AgentName</agent-pending-action-key>
            <agent-pending-action-val>VW-PUN-BNA-DV21.punbnadv21.local</agent-pending-action-val>
            <operand>equals</operand>
          </filter>
        </filters>
      </command-parameters>
    </command-request>
  </scom-request>
</request-data> 

The following figure shows the sample adapter response.

Adapter response for the Find Agent Pending Action operation

<scom-response>
  <metadata>
    <status>success</status>
    <count>1</count>
  </metadata>
  <commands-output>
    <command-output>
      <metadata>
        <command> Import-Module OperationsManager; Get-SCOMPendingManagement | where-object {$_.AgentPendingActionType -eq 'RepairAgent'} | where-object {$_.AgentName -eq 'VW-PUN-BNA-DV21.punbnadv21.local'} | format-list</command>
        <execution-milliseconds>41342</execution-milliseconds>
        <exit-code>0</exit-code>
        <status>success</status>
        <count>1</count>
      </metadata>
      <output>
        <item>
          <AgentName><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></AgentName>
          <ManagementServerName><![CDATA[VW-PUN-BNA-DV22.punbnadv21.local]]></ManagementServerName>
          <AgentPendingActionType><![CDATA[RepairAgent]]></AgentPendingActionType>
          <LastModified>01/05/2017 01:34:36 AM</LastModified>
          <ManagementGroup><![CDATA[SCOM-GROUP]]></ManagementGroup>
          <ManagementGroupId><![CDATA[f0bfdf68-bb60-15e4-e21a-3678feeaa78e]]></ManagementGroupId>
        </item>
      </output>
    </command-output>
  </commands-output>
</scom-response> 

Find Agent operation

The Find Agent operation retrieves the agents associated with the Microsoft System Center Operations Manager 2012 management server. You can filter the result by specifying a filter criterion. 

The following table shows the adapter request elements for the Find Agent operation.

Adapter request elements for the Find Agent operation

ElementDefinitionRequired

<operation-name>

Specifies the operation name: get-SCOMAgent

Yes

<timeout-secs>

Specifies the duration after which the operation times out 

Default value: 60 seconds

No

<command-parameters>

Specifies the parent element for the command parameters

Yes

<filters>

Specifies the parent element that contains the search criterion

No

<filter>

Specifies the parent element for a single search criterion 

You can specify more than one filter criterion by using multiple <filter> elements.

Conditional; required if the <filters> element is specified

<agent-prop-key>

Specifies the name of the agent's property used in the search 

Valid values:

  • PrimaryManagementServerName
  • InstalledBy
  • ManuallyInstalled
  • Version
  • ActionAccountIdentity
  • Name
  • Id
  • DisplayName
  • HostComputer
  • HostedHealthService
  • HealthState
  • PrincipalName
  • NetworkName
  • ComputerName
  • Domain
  • RequestCompression
  • CommunicationPort
  • ManuallyInstalled
  • AuthenticationName
  • HeartbeatInterval

Conditional; required if the <filters> element is specified

<agent-prop-val>

Specifies the value of the property specified in the <agent-prop-key> element

Conditional; required if the <filters> element is specified

<operand>

Specifies the operation that is performed by using the values specified in the <agent-prop-key> and <agent-prop-val> elements 

Valid values:

  • equals
  • not equals
  • matches

Conditional; required if the <filters> element is specified

The following figure shows the <items> XML for the Find Agent operation.

<items> XML for the Find Agent operation

<items>
  <item>
  <operation-name>get-SCOMAgent</operation-name>
  <timeout-secs>120</timeout-secs>
   <command-parameters>
     <filters>
       <filter>
        <agent-prop-key>PrimaryManagementServerName</agent-prop-key>
        <agent-prop-val>win2stdvm</agent-prop-val>
        <operand>matches</operand>
      </filter>
     </filters>
   </command-parameters>
  </item>
  <item>
  <operation-name>get-SCOMAgent</operation-name>
  <timeout-secs>120</timeout-secs>
  <command-parameters>
   <filters>
    <filter>
     <agent-prop-key>InstalledBy</agent-prop-key>
     <agent-prop-val>SYNAPSE\vikas.malhotra</agent-prop-val>
     <operand>equals</operand>
    </filter>
   </filters>
  </command-parameters>
 </item>
</items>

The following figure shows the sample adapter request.

Sample adapter request XML for the Find Agent operation

<request-data>
  <scom-request>
    <operation-name>Get-SCOMAgent</operation-name>
    <command-request>
      <timeout-secs>120</timeout-secs>
      <command-parameters>
        <managementserver>
          <filters>
            <filter>
              <managementserver-prop-key>Name</managementserver-prop-key>
              <managementserver-prop-val>VW-PUN-BNA-DV22.punbnadv21.local</managementserver-prop-val>
              <operand>equals</operand>
            </filter>
          </filters>
        </managementserver>
      </command-parameters>
    </command-request>
  </scom-request>
</request-data> 

The following figure shows the adapter response.

Adapter response for the Find Agent operation

<scom-response>
  <metadata>
    <status>success</status>
    <count>1</count>
  </metadata>
  <commands-output>
    <command-output>
      <metadata>
        <command> Import-Module OperationsManager; Get-SCOMAgent -managementserver ((Get-SCOMManagementServer) | where-object {$_.Name -eq 'VW-PUN-BNA-DV22.punbnadv21.local'}) | format-list</command>
        <execution-milliseconds>77688</execution-milliseconds>
        <exit-code>0</exit-code>
        <status>success</status>
        <count>1</count>
      </metadata>
      <output>
        <item>
          <PatchList><![CDATA[(null)]]></PatchList>
          <PrimaryManagementServerName><![CDATA[VW-PUN-BNA-DV22.punbnadv21.local]]></PrimaryManagementServerName>
          <ManagementGroup><![CDATA[SCOM-GROUP]]></ManagementGroup>
          <Id><![CDATA[cdc7621c-a802-c4fd-00e6-76b239da5a33]]></Id>
          <LastModified>01/04/2017 06:12:46 AM</LastModified>
          <Name><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></Name>
          <DisplayName><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></DisplayName>
          <HostComputer><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></HostComputer>
          <HostedHealthService><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></HostedHealthService>
          <HealthState>Healthy</HealthState>
          <PrincipalName><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></PrincipalName>
          <NetworkName><![CDATA[VW-PUN-BNA-DV21.punbnadv21.local]]></NetworkName>
          <ComputerName><![CDATA[VW-PUN-BNA-DV21]]></ComputerName>
          <Domain><![CDATA[PUNBNADV21]]></Domain>
          <IPAddress><![CDATA[10.129.83.175]]></IPAddress>
          <Version></Version>
          <RequestCompression><![CDATA[True]]></RequestCompression>
          <CommunicationPort><![CDATA[5723]]></CommunicationPort>
          <MaximumSizeOfAllTransferredFilesBytes><![CDATA[0]]></MaximumSizeOfAllTransferredFilesBytes>
          <MaximumQueueSizeBytes><![CDATA[104857600]]></MaximumQueueSizeBytes>
          <ManuallyInstalled><![CDATA[False]]></ManuallyInstalled>
          <InstallTime>01/04/2017 06:11:36 AM</InstallTime>
          <InstalledBy><![CDATA[VW-PUN-BNA-DV22\Administrator]]></InstalledBy>
          <CreateListener><![CDATA[False]]></CreateListener>
          <AuthenticationName></AuthenticationName>
          <ActionAccountIdentity></ActionAccountIdentity>
          <HeartbeatInterval><![CDATA[60]]></HeartbeatInterval>
          <ProxyingEnabled><![CDATA[False]]></ProxyingEnabled>
          <ManagementGroupId><![CDATA[00000000-0000-0000-0000-000000000000]]></ManagementGroupId>
        </item>
      </output>
    </command-output>
  </commands-output>
</scom-response>

Reject Agent Pending Action operation

The Reject Agent Pending Action operation rejects the action that is pending with an agent. You can filter the agents by specifying a filter criterion. 

The following table describes the request elements for the Reject Agent Pending Action operation:

Adapter request elements for the Reject Agent Pending Action operation

Element

Definition

Required

<operation-name>

Specifies the operation name: Deny-SCOMPendingManagement

Yes

<timeout-secs>

Specifies the duration after which the operation times out 

Default value: 60 seconds

No

<command-parameters>

Specifies the parent element for the command parameters

Yes

<agent-pending-action>

Specifies the parent element that contains the filter criterion used to retrieve the agents that have actions in the pending state

Yes

<filters>

Specifies the parent element that contains the search criterion

No

<filter>

Specifies the parent element for a single search criterion 

You can specify more than one filter criterion by using multiple <filter> elements.

Conditional; required if the <filters> element is specified

<agent-pending-action-key>

Specifies the key that is used to locate an agent 

Valid values:

  • AgentName
  • ManagementServerName
  • AgentPendingActionType
  • ManagementGroup
  • ManagementGroupId

Conditional; required if the <filters> element is specified

<agent-pending-action-val>

Specifies the value of the key specified in the <agent-pending-action-key> element

Conditional; required if the <filters> element is specified

<operand>

Specifies the operation that is performed by using the values specified in the <agent-pending-action-key> and <agent-pending-action-val> elements 

Valid values:

  • equals
  • not equals
  • matches

Conditional; required if the <filters> element is specified

<preview>

Specifies whether you want to preview the results of the operation 

Valid values:

  • true: Indicates that you want to preview the results of the operation
  • false: Indicates that the operation is executed without displaying the results of the execution (default)

No

 The following figure shows the <items> XML for the Reject Agent Pending Action operation.

<items> XML for the Reject Agent Pending Action operation

<items>
  <item>
  <operation-name>Deny-SCOMPendingManagement</operation-name>
  <timeout-secs>120</timeout-secs>
<command-parameters>
<agent-pending-action>
<filters>
	<filter>
		<agent-pending-action-key>AgentName</agent-pending-action-key>
		<agent-pending-action-val>abc.synapse.com</agent-pending-action-val>
		<operand>matches</operand>
	</filter>
</filters>
</agent-pending-action>
<preview>true</preview>
</command-parameters>
  </item>
</items>

The following figure shows the sample adapter request.

Sample adapter request XML for the Reject Agent Pending Action operation

<request-data>
  <scom-request>
    <operation-name>Deny-SCOMPendingManagement</operation-name>
    <command-request>
      <timeout-secs>120</timeout-secs>
      <command-parameters>
        <agent-pending-action>
          <filters>
            <filter>
              <agent-pending-action-key>AgentPendingActionType</agent-pending-action-key>
              <agent-pending-action-val>RepairAgent</agent-pending-action-val>
              <operand>equals</operand>
            </filter>
            <filter>
              <agent-pending-action-key>AgentName</agent-pending-action-key>
              <agent-pending-action-val>VW-PUN-BNA-DV21.punbnadv21.local</agent-pending-action-val>
              <operand>matches</operand>
            </filter>
          </filters>
        </agent-pending-action>
        <preview>false</preview>
      </command-parameters>
    </command-request>
  </scom-request>
</request-data> 

The following figure shows the adapter response.

Adapter response for the Reject Agent Pending Action operation

<scom-response>
  <metadata>
    <status>success</status>
    <count>1</count>
  </metadata>
  <commands-output>
    <command-output>
      <metadata>
        <command> Import-Module OperationsManager; Deny-SCOMPendingManagement -pendingaction ((Get-SCOMPendingManagement) | where-object {$_.AgentPendingActionType -eq 'RepairAgent'} | where-object {$_.AgentName -match 'VW-PUN-BNA-DV21.punbnadv21.local'}) | format-list</command>
        <execution-milliseconds>74258</execution-milliseconds>
        <exit-code>0</exit-code>
        <status>success</status>
        <count>0</count>
      </metadata>
      <output />
    </command-output>
  </commands-output>
</scom-response> 

Uninstall Agent operation

The Uninstall Agent operation uninstalls the Operations Manager agent from the specified managed computers.

The following table describes the adapter request elements for the Uninstall Agent operation. 

Adapter request elements for the Uninstall Agent operation 

ElementDefinitionRequired

<operation-name>

Specifies the operation name: uninstall-SCOMAgent

Yes

<command-request>

Specifies the parent element for the command elements

Yes

<timeout-secs>

Specifies the duration after which the operation times out 

Default value: 60 seconds

No

<command-parameters>

Specifies the parent element for the command parameters

Yes

<agent-managed-computer>

Specifies the search criterion used to identify a computer that has an agent installed on it

Yes

<filters>

Specifies the parent element that contains the search criterion

No

<filter>

Specifies the parent element for a single search criterion 

You can specify more than one filter criterion by using multiple <filter> elements.

Conditional; required if the <filters> element is specified

<agent-prop-key>

Specifies the name of the agent's property used in the search

Conditional; required if the <filters> element is specified

<agent-prop-val>

Specifies the value of the property specified in the <agent-prop-key> element

Conditional; required if the <filters> element is specified

<operand>

Specifies the operation that is performed by using the values specified in the <agent-prop-key> and <agent-prop-val>elements 

Valid values:

  • equals
  • not equals
  • matches

Conditional; required if the <filters> element is specified

<preview>

Specifies whether you want to preview the results of the operation 

Valid values:

  • true: Indicates that you want to preview the results of the operation
  • false: Indicates that the operation is executed without displaying the results of the execution (default)

No

The following figure shows the <items> XML for the Uninstall Agent operation. 

<items> XML for the Uninstall Agent operation

<items>
  <item>
  <operation-name>uninstall-SCOMAgent</operation-name>
  <timeout-secs>120</timeout-secs>
  <command-parameters>
   <agent-managed-computer>
     <filters>
      <filter>
       <agent-prop-key>Name</agent-prop-key>
       <agent-prop-val>D-13096.synapse.com</agent-prop-val>
       <operand>equals</operand>
      </filter>
     </filters>
   </agent-managed-computer>
   <preview>true</preview>
  </command-parameters>
  </item>
</items>

The following figure shows the sample adapter request.

Sample adapter request XML for the Uninstall Agent operation

<request-data>
  <scom-request>
    <operation-name>Uninstall-SCOMAgent</operation-name>
    <command-request>
      <timeout-secs>320</timeout-secs>
      <command-parameters>
        <agent-managed-computer>
          <filters>
            <filter>
              <agent-prop-key>Name</agent-prop-key>
              <agent-prop-val>VW-PUN-BNA-DV21.punbnadv21.local</agent-prop-val>
              <operand>equals</operand>
            </filter>
          </filters>
        </agent-managed-computer>
        <whatif>false</whatif>
      </command-parameters>
    </command-request>
  </scom-request>
</request-data> 

The following figure shows the adapter response. 

Adapter response for the Uninstall Agent operation

<scom-response>
  <metadata>
    <status>success</status>
    <count>1</count>
  </metadata>
  <commands-output>
    <command-output>
      <metadata>
        <command> Import-Module OperationsManager; Uninstall-SCOMAgent -agent ((Get-SCOMAgent) | where-object {$_.Name -eq 'VW-PUN-BNA-DV21.punbnadv21.local'}) | format-list</command>
        <execution-milliseconds>135580</execution-milliseconds>
        <exit-code>0</exit-code>
        <status>success</status>
        <count>0</count>
      </metadata>
      <output />
    </command-output>
  </commands-output>
</scom-response> 

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments