# Managed Object - Agency

Property of
  AgencyIssue, AgentRuntimeInfo, EsxAgentManager, ExtensibleIssue
Returned by
  CreateAgency, QueryAgency
Extends
  EamObject
See also
  AgencyConfigInfo, Agent, EamObjectRuntimeInfo, Issue, vim.VirtualMachine

## Managed Object Description

An `Agency` handles the deployment of a single type of agent virtual machine and any associated VIB bundle, on a set of compute resources.

For a solution to deploy multiple types of agents, it must create multiple agencies by using `createAgency` on EsxAgentManager (see EsxAgentManager#createAgency(Agency.ConfigInfo,String)).

Creating an agency is a long-running process. vSphere ESX Agent Manager must install VIBs, configure hosts, install agent virtual machines and do many more things. Each of these steps can take a considerable amount of time. vSphere ESX Agent Manager can also encounter problems when creating the agency. In this case, the solution must remediate the problem. See Issue for a description of the kinds of issue that vSphere ESX Agent Manager will raise. Similarly, removing an agency from vSphere ESX Agent Manager is also a long-running process that involves many steps. Removing an agency can also raise issues.

Use the `goalState` and `status` properties to show the progress of creating or removing an Agency. The `goalState` and `status` properties are found in the runtime information of an `Agency` (see status in Agency#runtime()):

- `goalState`. The goal state describes the overall goal of an `Agency`. The goal state can be `enabled` or `uninstalled`:
  - `enabled`. The `Agency` continuously deploys VIBs and agent virtual machines, powers on agent virtual machines, and monitors agents for issues.
  - `uninstalled`. The `Agency` uninstalls any installed VIBs and powers off and deletes any deployed agent virtual machines.
- `status`. The status of the `Agency` regarding the given goal state. Status can be either red, yellow or green:
  - `red`. An issue is preventing the `Agency` from reaching its desired goal state. See issue in Agency#runtime() for the types of issues that can block this `Agency`.
  - `yellow`. The `Agency` is actively working to reach the desired goal state. For the `enabled` goal state, this means that this `Agency` is currently installing VIBs, deploying agent virtual machines, and powering them on.
  - `green`. The `Agency` has reached the desired goal state. The `Agency` is no longer actively scheduling new tasks but is monitoring the vCenter Server for changes that might conflict with this `Agency`'s goal state.

The following image shows in general terms how the status changes in the life-cycle of an `Agency`.

"Agency degraded" means that something has happened in the vCenter Server that causes this `Agency` to actively schedule new tasks to reach the goal state. For example, adding a host to a cluster covered by the scope of the `Agency`, which causes ESX Agent Manager to install a VIB and deploy an agent virtual machine on the new host. A solution should monitor the list of issues associated with this `Agency`.

The solution can poll Agency#runtime().

Properties

Name | Type | Description
--- | --- | ---
agent* | vmodl.ManagedObjectReference to a Agent[] | An array of agents deployed by this agent manager. Requires view privileges.
config | AgencyConfigInfo | The configuration of this `Agency`. Specifies how this `Agency` deploys its agents and VIBs. Requires view privileges.
owner* | xsd:string | The principal name of the user that owns this `Agency`. If the agency is owned by a VC extension, this method returns null. Requires view privileges. Since vEAM API 6.0
runtime | EamObjectRuntimeInfo | Gets the runtime information for this agency. Requires view privileges.
solutionId | xsd:string | The ID of the solution that owns this `Agency`. If the agency is owned by a VC extension, this is the extension's key. Otherwise, this is same as Agency#owner(). The users in the latter case are either regular or solution users. Requires view privileges.
Properties inherited from EamObject
None

*May not be present

Methods

Methods defined in this Managed Object
AddIssue, AgencyQueryRuntime, DestroyAgency, Disable, Enable, QueryAgent, QueryConfig, QuerySolutionId, RegisterAgentVm, Uninstall, UnregisterAgentVm, Update
Methods inherited from EamObject
QueryIssue, Resolve, ResolveAll

# AddIssue

Deprecated.

Adds an issue to this agency. Issue#key and Issue#time is overwritten so that Issue#key becomes unique on this server and Issue#time is the current time.

Requires modify privileges.

Required Privileges
  None
Since
  vEAM API 2.0

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.
issue | Issue | A new issue.

Return Value

Type | Description
--- | ---
Issue | The same issue where the key and time is set.

Faults

Type | Description
--- | ---
vmodl.fault.InvalidArgument |

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AddIssue" type="eam:AddIssueRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AddIssueResponse"> <complexType> <sequence> <element name="returnval" type="eam:Issue"/> </sequence> </complexType> </element>

# AgencyQueryRuntime

Deprecated. Use #runtime() instead

Gets the runtime information for this agency.

Requires view privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
EamObjectRuntimeInfo | The runtime information.

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AgencyQueryRuntime" type="eam:AgencyQueryRuntimeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AgencyQueryRuntimeResponse"> <complexType> <sequence> <element name="returnval" type="eam:EamObjectRuntimeInfo"/> </sequence> </complexType> </element>

# DestroyAgency

Destroys this Agency. Any agents that the `Agency` has are removed. Until the agents have been removed, it is possible to view the runtime state of this `Agency` but it is not possible to modify its configuration or change its goal state. After all agents have been removed, any subsequent call on this `Agency` will throw a `ManagedObjectNotFound` exception.

Requires modify privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="DestroyAgency" type="eam:DestroyAgencyRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="DestroyAgencyResponse"> <complexType/> </element>

# Disable

Deprecated. its definition is not consistent accross agent VMs and VIBs. It is impossible to be defined since there is no corresponding state of ESXi vibs.

Sets the goal state of this `Agency` to `disabled`. This powers off any powered on agent virtual machines, but continues provisioning agents to hosts that are added to the compute resources in the agency's scope, and removes agents from hosts that are taken out of the scope.

Requires modify privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Disable" type="eam:DisableRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="DisableResponse"> <complexType/> </element>

# Enable

Deprecated. since agencies are always created as enabled. In addition, enabling already uninstalled agency is not supported.

Sets the goal state of this `Agency` to `enabled`. This causes the agency to continuously deploy and monitor agents.

Requires modify privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Enable" type="eam:EnableRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="EnableResponse"> <complexType/> </element>

# QueryAgent

Deprecated. Use #agent() instead

An array of agents deployed by this agent manager.

Requires view privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
vmodl.ManagedObjectReference to a Agent[] |

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryAgent" type="eam:QueryAgentRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryAgentResponse"> <complexType> <sequence> <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element>

# QueryConfig

Deprecated. Use #config() instead

The configuration of this `Agency`. Specifies how this `Agency` deploys its agents and VIBs.

Requires view privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
AgencyConfigInfo | The configuration of this `Agency`.

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryConfig" type="eam:QueryConfigRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryConfigResponse"> <complexType> <sequence> <element name="returnval" type="eam:AgencyConfigInfo"/> </sequence> </complexType> </element>

# QuerySolutionId

Deprecated. Use #solutionId() instead

The ID of the solution that owns this `Agency`. If the agency is owned by a VC extension, this is the extension's key. Otherwise, this is same as Agency#owner(). The users in the latter case are either regular or solution users.

Requires view privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
xsd:string | The solution ID.

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QuerySolutionId" type="eam:QuerySolutionIdRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QuerySolutionIdResponse"> <complexType> <sequence> <element name="returnval" type="xsd:string"/> </sequence> </complexType> </element>

# RegisterAgentVm

Deprecated. use automatically provisioned VMs and register hooks to have control post provisioning and power on

Adds an agent VM to this agency. Used if manuallyProvisioned is set to true. The method does nothing if the agent VM is already registered with this agency.

Requires modify privileges.

Required Privileges
  None
Since
  vEAM API 2.0

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.
agentVm | vmodl.ManagedObjectReference to a vim.VirtualMachine | The managed object reference to the agent VM.

Return Value

Type | Description
--- | ---
vmodl.ManagedObjectReference to a Agent |

Faults

Type | Description
--- | ---
vmodl.fault.ManagedObjectNotFound |

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="RegisterAgentVm" type="eam:RegisterAgentVmRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="RegisterAgentVmResponse"> <complexType> <sequence> <element name="returnval" type="vim25:ManagedObjectReference"/> </sequence> </complexType> </element>

# Uninstall

Sets the goal state of this `Agency` to `uninstalled`. This initiates the uninstallation of this `Agency`, which causes all agents to be removed.

The best practice when destroying an agency is to call `uninstall`, wait for the runtime status to turn green, and then invoke Agency#destroyAgency(). When waiting for this `Agency` to be uninstalled the solution can then attend to and resolve any raised issues.

Requires modify privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Uninstall" type="eam:UninstallRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UninstallResponse"> <complexType/> </element>

# UnregisterAgentVm

Deprecated. use automatically provisioned VMs and register hooks to have control post provisioning and power on

Removes an agent VM to this agency. Used if manuallyProvisioned is set to true. The method does nothing if the agent VM is not registered with this agency.

Requires modify privileges.

Required Privileges
  None
Since
  vEAM API 2.0

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.
agentVm | vmodl.ManagedObjectReference to a vim.VirtualMachine | The managed object reference to the agent VM.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
None

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UnregisterAgentVm" type="eam:UnregisterAgentVmRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UnregisterAgentVmResponse"> <complexType/> </element>

# Update

Updates the agency configuration used by this `Agency` to deploy agents and VIBs. vSphere ESX Agent Manager generates a diff between the old configuration and the new one and updates the `Agency` accordingly.

Requires modify privileges.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | vmodl.ManagedObjectReference | A reference to the Agency used to make the method call.
config | AgencyConfigInfo | The new configuration for this `Agency`

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
InvalidAgencyScope | Thrown if one or more compute resources in the scope cannot be found in vCenter.
InvalidAgentConfiguration | Thrown if one or more agent configurations are invalid.
InvalidUrl | Thrown if either the agent virtual machine URL or VIB URL cannot be parsed or if the resource refered to cannot be downloaded.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Update" type="eam:UpdateRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UpdateResponse"> <complexType/> </element>