Managed Object - Folder

Property of
Datacenter, FolderEventArgument, HostConnectSpec, ServiceContent, VAppCloneSpec, VirtualApp
Parameter to
CloneVM_Task, CreateVApp, ImportVApp
Returned by
CreateFolder
Extends
ManagedEntity
See also
ClusterComputeResource, ClusterConfigSpec, ClusterConfigSpecEx, ComputeResource, ComputeResourceConfigSpec, Datacenter, DistributedVirtualSwitch, DVSCreateSpec, HostConnectSpec, HostSystem, ManagedEntity, ResourcePool, 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:

Properties

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 can contain Network, DistributedVirtualSwitch, and DistributedVirtualPort managed 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

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

AddStandaloneHost_Task

Creates a new single-host compute resource. The name provided can be an IP address, such as 192.168.0.120, 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 esx120.vmware.com. 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.

Required Privileges
Host.Inventory.AddStandaloneHost

Parameters

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

The host name, port, and passwords for the host to be added.
compResSpec*ComputeResourceConfigSpec

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

Since VI API 2.5
addConnectedxsd:boolean

Flag to specify whether or not the host should be connected as soon as it is added. The creation operation fails if a connection attempt is made and fails.
license*xsd:string

Provide a licenseKey or licenseKeyType. See LicenseManager

Since vSphere API 4.0
*Need not be set

Return Value

Type Description
ManagedObjectReference
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.

Faults

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



CreateCluster

Deprecated. As of VI API 2.5, use CreateClusterEx.

Creates a new cluster compute resource in this folder.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

Required Privileges
Host.Inventory.CreateCluster

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
namexsd:string

Name for the new cluster.
specClusterConfigSpec

Specification for the cluster.

Return Value

Type Description
ManagedObjectReference
to a ClusterComputeResource
A new ClusterComputeResource instance.

Faults

Type Description
DuplicateNameThrown if an entity with that name already exists.
InvalidArgumentThrown if the cluster configuration specification parameter is invalid.
InvalidNameThrown if the name is not a valid entity name.
NotSupportedThrown if the cluster is being added to a folder whose childType property value does not contain "ComputeResource" or "ClusterComputeResource".
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CreateClusterEx

Creates a new cluster compute resource in this folder.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

Required Privileges
Host.Inventory.CreateCluster
Since
VI API 2.5

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
namexsd:string

Name for the new cluster.
specClusterConfigSpecEx

Specification for the cluster.

Return Value

Type Description
ManagedObjectReference
to a ClusterComputeResource
A new ClusterComputeResource instance.

Faults

Type Description
DuplicateNameThrown if an entity with that name already exists.
InvalidArgumentThrown if the cluster configuration specification parameter is invalid.
InvalidNameThrown if the name is not a valid entity name.
NotSupportedThrown if the cluster is being added to a folder whose childType property value does not contain "ComputeResource" or "ClusterComputeResource".
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CreateDatacenter

Creates a new datacenter with the given name.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

Required Privileges
Datacenter.Create

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
namexsd:string

Name for the new datacenter. An entity name must be a non-empty string of less than 80 characters. The slash (/), backslash (\) and percent (%) will be escaped using the URL syntax. For example, %2F.

Return Value

Type Description
ManagedObjectReference
to a Datacenter
A new Datacenter instance.

Faults

Type Description
DuplicateNameThrown if an entity with that name already exists.
InvalidNameThrown if the new name is not a valid entity name.
NotSupportedThrown if the datacenter is being created within a folder whose childType property value does not contain "Datacenter".
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CreateDVS_Task

Create a Distributed Virtual Switch in the folder according to the specified (@link vim.DistributedVirtualSwitch.CreateSpec).
Required Privileges
DVSwitch.Create
Since
vSphere API 4.0

Parameters

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

The (@link vim.DistributedVirtualSwitch.CreateSpec) to create the Distributed Virtual Switch.

Return Value

Type Description
ManagedObjectReference
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 registered DistributedVirtualSwitch upon success.

Faults

Type Description
DuplicateName
DvsFault
DvsNotAuthorizedThrown if login-session's extension key does not match (@link vim.DistributedVirtualSwitch.ConfigInfo#extensionKey).
InvalidName
NotFound
NotSupportedThrown if called directly on a host.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.



CreateFolder

Creates a new sub-folder with the specified name. The childType property of the new folder is the same as the childType property of the current folder.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

Required Privileges
Folder.Create

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
namexsd:string

The name to be given the new folder. An entity name must be a non-empty string of less than 80 characters. The slash (/), backslash (\) and percent (%) will be escaped using the URL syntax. For example, %2F.

Return Value

Type Description
ManagedObjectReference
to a Folder
A reference to the new folder.

Faults

Type Description
DuplicateNameThrown if another object in the same folder has the target name.
InvalidNameThrown if the name is not a valid entity name.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CreateVM_Task

Creates a new virtual machine in the current folder and attaches it to the specified resource pool. This operation creates a virtual machine, instead of cloning a virtual machine from an existing one.

The server does not support creating templates using this method. Instead, you should create templates by marking existing virtual machines as templates, or by cloning an existing virtual machine or template.

This operation only works if the folder's childType includes VirtualMachine. In addition to the VirtualMachine.Inventory.Create privilege, may also require any of the following privileges depending on the properties of the virtual machine bring created:

Required Privileges
VirtualMachine.Inventory.Create

Parameters

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

The configuration of the virtual machine hardware.
pool PManagedObjectReference
to a ResourcePool

The resource pool to which the virtual machine will be attached.
host*ManagedObjectReference
to a HostSystem

The target host on which the virtual machine will run. This must specify a host that is a member of the ComputeResource indirectly specified by the pool. For a stand-alone host or a cluster with DRS, host can be omitted, and the system selects a default.
*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type Description
ManagedObjectReference
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 created VirtualMachine upon success.

Faults

Type Description
DuplicateNameThrown if another virtual machine in the same folder already has the specified target name.
FileAlreadyExistsThrown if the requested cfgPath for the virtual machine's configuration file already exists.
FileFaultThrown if there is a problem creating the virtual machine on disk. Typically, a more specific subclass, such as NoDiskSpace, will be thrown.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
InvalidNameThrown if the name is not a valid entity name.
NotSupportedThrown if the virtual machine is being created within a folder whose childType property is not set to "VirtualMachine".
OutOfBoundsThrown if Host.capability.maxSupportedVMs is exceeded.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFaultThrown if the configSpec has incorrect values. Typically, a more specific subclass is thrown.
VmWwnConflictThrown if the WWN of the virtual machine has been used by other virtual machines.



MoveIntoFolder_Task

Moves a set of managed entities into this folder.

This operation is typically used by clients when they implement a drag-and-drop interface to move a set of objects into a folder.

This operation is transactional only with respect to each individual entity. The set of entities is moved sequentially as specified in the list, and committed one at a time. If the MoveIntoFolder_Task method fails on an object, the method terminates at that point with an exception, leaving the rest of the managed entities in their original location.

The objects that can be moved into a folder depends on the folder's type (as defined by the folder's childType property). For a datacenter folder, only datacenters and datacenter folders can be moved into the folder. For a virtual machine folder, only virtual machines and virtual machine folders can be moved into the folder. For a host folder, ComputeResource objects, host folder objects, and HostSystem objects can be moved into the folder.

Moving a HostSystem into a host folder creates a stand-alone host from a host that is currently part of a ClusterComputeResource. The host must be part of a ClusterComputeResource in the same datacenter and the host must be in maintenance mode. Otherwise, the operation fails.

A ComputeResource with a single root resource pool is created for each HostSystem. The name of the ComputeResource is the DNS or IP address of the host. This operation moves the (physical) host resources out of a cluster. It does not move or change the ResourcePool configuration that is part of the ClusterComputeResource with which the host was associated.

Note that all virtual machines associated with a host are moved with the host into the folder. If there are virtual machines that should not be moved with the host, then migrate them from the host before initiating this operation.

For a HostSystem move, the privileges required are Host.Inventory.EditCluster on the source ClusterComputeResource, Host.Inventory.MoveHost on the HostSystem, and Host.Inventory.AddStandaloneHost on the target Folder.

Otherwise, the privilege required for this operation varies depending on this folder's type and is checked against the source container, destination container, and the object:

If the object is a HostSystem, the privileges required are Host.Inventory.AddStandaloneHost on the folder, Host.Inventory.MoveHost on the HostSystem, and Host.Inventory.EditCluster on the host's original ComputeResource.
Required Privileges
Dynamic - See discussion above

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
listManagedObjectReference[]
to a ManagedEntity[]

The list of objects to be moved into the folder.

Return Value

Type Description
ManagedObjectReference
to a Task
This method returns a Task object with which to monitor the operation.

Faults

Type Description
DisallowedOperationOnFailoverHostThrown if the host is being moved out of a cluster and was configured as a failover host in that cluster. See ClusterFailoverHostAdmissionControlPolicy.
DuplicateNameThrown if this folder already contains an object with the specified name.
InvalidFolderThrown if a Folder that is a parent of this Folder is part of the list of objects.
InvalidStateThrown if a HostSystem is not part of the same datacenter, not part of a ClusterComputeResource, or not in maintenance mode.
NotSupportedThrown if the entity is being moved into a folder whose childType property is not set to the appropriate value. For example, a VirtualMachine entity cannot be moved into a folder whose ChildType property value does not contain "VirtualMachine".
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmAlreadyExistsInDatacenterThrown if moving a standalone host between datacenters, and one or more of the host's virtual machines is already registered to a host in the destination datacenter.



RegisterVM_Task

Adds an existing virtual machine to the folder.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

This operation only works if the folder's type is VirtualMachine.

Required Privileges
VirtualMachine.Inventory.Register

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the Folder used to make the method call.
pathxsd:string

A datastore path to the virtual machine.
name*xsd:string

The name to be assigned to the virtual machine. If this parameter is not set, the displayName configuration parameter of the virtual machine is used. An entity name must be a non-empty string of less than 80 characters. The slash (/), backslash (\) and percent (%) will be escaped using the URL syntax. For example, %2F.
asTemplatexsd:boolean

Flag to specify whether or not the virtual machine should be marked as a template.
pool* PManagedObjectReference
to a ResourcePool

The resource pool to which the virtual machine should be attached. If imported as a template, this parameter is not set.
host*ManagedObjectReference
to a HostSystem

The target host on which the virtual machine will run. This parameter must specify a host that is a member of the ComputeResource indirectly specified by the pool. For a stand-alone host or a cluster with DRS, the parameter can be omitted, and the system selects a default.
*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type Description
ManagedObjectReference
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 registered VirtualMachine upon success.

Faults

Type Description
AlreadyExistsThrown if the virtual machine is already registered.
DuplicateNameThrown if another virtual machine in the same folder has the target name.
FileFaultThrown if there is an error accessing the files on disk.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidArgumentThrown if any of the arguments such as host or resource pool are not set to valid values.
InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
InvalidNameThrown if the entity name is invalid.
NotFoundThrown if the configuration file is not found on the system.
NotSupportedThrown if the operation is not supported. For example, templates are not supported directly on hosts. Also, if the operation is invoked on a folder whose childType property is not set to "VirtualMachine".
OutOfBoundsThrown if the maximum number of VMs for this folder has been exceeded. The maximum number is determined by Host.capability.maxSupportedVMs.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFaultThrown if the format / configuration of the virtual machine is invalid. Typically, a more specific fault is thrown such as InvalidFormat if the configuration file cannot be read, or InvalidDiskFormat if the disks cannot be read.



UnregisterAndDestroy_Task

Recursively unregisters all virtual machines and vApps, and destroys all child virtual machine folders. This is similar to the Destroy_Task method, but this method calls UnregisterAndDestroy_Task on each virtual machine object instead of calling Destroy_Task. This operation applies only to VirtualMachine folders.

UnregisterAndDestroy_Task is a recursive operation that destroys the specified virtual machine folder, unregisters all child virtual machine objects, and destroys all child virtual machine folders. When you call UnregisterAndDestroy_Task to destroy a virtual machine folder, the system uses the specified folder as a root and traverses its descendant hierarchy, calling UnregisterAndDestroy_Task on each virtual machine object and Destroy_Task on each virtual machine folder. UnregisterAndDestroy_Task is a single operation that treats each recursive call as a single transaction, committing each call to remove an object individually. If a failure occurs, the method terminates at that point with an exception, leaving some or all objects unaffected.

If you are removing virtual machines, you must hold the VirtualMachine.Delete privilege on all of the virtual machines to be unregistered, and on their parent folders. If you are removing virtual applications, you must hold the VApp.Delete privilege on all of the virtual applications to be unregistered, and on their parent folders.

Required Privileges
Folder.Delete

Parameters

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

Return Value

Type Description
ManagedObjectReference
to a Task
This method returns a Task object with which to monitor the operation.

Faults

Type Description
ConcurrentAccessThrown if another client modifies the folder contents before this operation completes.
InvalidStateThrown if a virtual machine is not powered off or suspended.
NotSupportedThrown if the childType property of the folder is not set to "VirtualMachine".
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.