Managed Object - Folder(vim.Folder)

Property of
Datacenter, FolderEventArgument, HostConnectSpec, NodeDeploymentSpec, ServiceContent, StoragePlacementSpec, VAppCloneSpec, VirtualApp, VirtualMachineRelocateSpec
Parameter to
CheckClone_Task, CloneVM_Task, CreateVApp, ImportVApp
Returned by
Extended by
See also
ClusterComputeResource, ClusterConfigSpec, ClusterConfigSpecEx, ComputeResource, ComputeResourceConfigSpec, Datacenter, DistributedVirtualSwitch, DVSCreateSpec, FolderBatchAddHostsToClusterResult, FolderBatchAddStandaloneHostsResult, FolderNewHostSpec, HostConnectSpec, HostSystem, ManagedEntity, ResourcePool, StoragePod, VirtualMachine, VirtualMachineConfigSpec

Managed Object Description

The Folder managed object is a container for storing and organizing inventory objects. Folders can contain folders and other objects. The childType property identifies a folder's type and determines the types of folders and objects the folder can contain. See ServiceInstance for a representation of the organization of the inventory.

The Folder managed object also acts as a factory object, meaning it creates new entities in a folder. The object provides methods to create child folders and objects, methods to add existing objects to folders, and methods to remove objects from folders and to delete folders.

Folder inherits the Destroy_Task method. Destroy_Task is a recursive operation that removes all child objects and folders. When you call Destroy_Task to destroy a folder, the system uses the specified folder as a root and traverses its descendant hierarchy, calling Destroy_Task on each object. Destroy_Task is a single operation that treats each recursive call as a single transaction, committing each call to remove an object individually. If Destroy_Task fails on an object, the method terminates at that point with an exception, leaving some or all of the objects still in the inventory.

Notes on the folder destroy method:


Name Type Description
childEntity* PManagedObjectReference[]
to a ManagedEntity[]

An array of managed object references. Each entry is a reference to a child entity.
childType* Pxsd:string[]

Specifies the object types a folder may contain. When you create a folder, it inherits its childType from the parent folder in which it is created. childType is an array of strings. Each array entry identifies a set of object types - Folder and one or more managed object types. The following list shows childType values for the different folders:
  • { "vim.Folder", "vim.Datacenter" } - Identifies the root folder and its descendant folders. Data center folders can contain child data center folders and Datacenter managed objects. Datacenter objects contain virtual machine, compute resource, network entity, and datastore folders.
  • { "vim.Folder", "vim.Virtualmachine", "vim.VirtualApp" } - Identifies a virtual machine folder. A virtual machine folder may contain child virtual machine folders. It also can contain VirtualMachine managed objects, templates, and VirtualApp managed objects.
  • { "vim.Folder", "vim.ComputeResource" } - Identifies a compute resource folder, which contains child compute resource folders and ComputeResource hierarchies.
  • { "vim.Folder", "vim.Network" } - Identifies a network entity folder. Network entity folders on a vCenter Server can contain Network, DistributedVirtualSwitch, and DistributedVirtualPortgroup managed objects. Network entity folders on an ESXi host can contain only Network objects.
  • { "vim.Folder", "vim.Datastore" } - Identifies a datastore folder. Datastore folders can contain child datastore folders and Datastore managed objects.

Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value
*May not be presentP Required privilege: System.View


Methods defined in this Managed Object
AddStandaloneHost_Task, BatchAddHostsToCluster_Task, BatchAddStandaloneHosts_Task, CreateCluster, CreateClusterEx, CreateDatacenter, CreateDVS_Task, CreateFolder, CreateStoragePod, CreateVM_Task, MoveIntoFolder_Task, RegisterVM_Task, UnregisterAndDestroy_Task
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject


Creates a new single-host compute resource. The name provided can be an IP address, such as, or a string, such as esx120. If a name is specified, a DNS lookup is used to resolve it to a fully-qualified name, such as If the DNS lookup fails, the string is stored as specified.

Licenses for the host are allocated when making the first connection to the host. This is because the license needed typically depends on the type of host and the number of CPUs.

In addition to the Host.Inventory.AddStandaloneHost privilege, it requires System.View privilege on the VM folder that the VMs of the host will be placed on.

Required Privileges


_thisManagedObjectReference A reference to the Folder used to make the method call.

Specifies the parameters needed to add a single host.

Optionally specify the configuration for the compute resource that will be created to contain the host.

Since VI API 2.5

Flag to specify whether or not the host should be connected as soon as it is added. The host will not be added if a connection attempt is made and fails.

Provide a licenseKey or licenseKeyType. See LicenseManager

Since vSphere API 4.0
*Need not be set

Return Value

Type Description
to a Task
This method returns a Task object with which to monitor the operation. The info.result property in the Task contains the newly added ComputeResource upon success.


Type Description
AgentInstallFailedThrown if there is an error installing the vCenter agent on the new host.
AlreadyBeingManagedThrown if the host is already being managed by a vCenter server. If the host is being managed by a different vCenter server, this can be overridden by the "force" flag in the connection specification.
AlreadyConnectedThrown if addConnected is true and the host is already connected to vCenter.
DuplicateNameThrown if another host in the same folder has the name.
GatewayConnectFaultThrown if the host is managed via host gateway and any error occured during the communication with the gateway
GatewayHostNotReachableThrown if the host is managed via host gateway and the gateway server cannot connect to the host
GatewayNotFoundThrown if the host is managed via host gateway and no available gateway server is found for the given parameters
GatewayNotReachableThrown if the host is managed via host gateway and vCenter Server cannot establish a network connection to the gateway server, or verify the gateway server's identity
GatewayOperationRefusedThrown if the gateway server cannot accept more host connections
GatewayToHostAuthFaultThrown if the host is managed via host gateway and the gateway server needs additional information to authenticate before the host
GatewayToHostTrustVerifyFaultThrown if the host is managed via host gateway and the gateway server cannot verify that the host is trusted
HostConnectFaultThrown if an error occurred when attempting to connect to a host. Typically, a more specific subclass, such as AlreadyBeingManaged, is thrown.
InvalidArgumentThrown if an argument is specified incorrectly.
InvalidLoginThrown if authentication with the host fails.
NoHostThrown if the host cannot be contacted.
NoPermissionThrown if there are crypto keys to be sent to the host, but the user does not have Cryptographer.RegisterHost privilege on the Folder.
NotEnoughLicensesThrown if there are not enough licenses to add the host.
NotSupportedThrown if the host is being added to a folder whose childType property does not contain "ComputeResource".
NotSupportedHostThrown if the host is running a software version that is not supported.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SSLVerifyFaultThrown if the host certificate could not be authenticated




Adds a set of new and existing hosts to the cluster. This API is a composite API and performs the following tasks before hosts become part of the specified cluter - The dynamic privilege check will ensure that appropriate privileges are acquired to allow this API to perform multiple actions on hosts and cluster. Required privileges -