| Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |
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* P | ManagedObjectReference[]
to a ManagedEntity[] |
An array of managed object references. Each entry is a reference to a child entity.
|
childType* P | xsd: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:
|
namespace* P | xsd:string |
The namespace with which the Folder is associated. Namespace is a vAPI
resource which divides cluster resources and allows administrators to
give Kubernetes environments to their development teams.
This property is set only at the time of creation and cannot change.
Since vSphere API 7.0 |
Properties inherited from ManagedEntity | ||
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState | ||
Properties inherited from ExtensibleManagedObject | ||
availableField, value |
Methods
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 |
setCustomValue |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
spec P | HostConnectSpec |
Specifies the parameters needed to add a single host.
Since 2.0 |
compResSpec* P | ComputeResourceConfigSpec |
Optionally specify the configuration for the compute
resource that will be created to contain the host.
Since 2.0 |
addConnected P | xsd:boolean |
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.
Since 2.0 |
license* P | xsd:string |
Provide a licenseKey or licenseKeyType. See LicenseManager
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly added ComputeResource upon success. |
Faults
Type | Description |
---|---|
AgentInstallFailed | Thrown if there is an error installing the vCenter agent on the new host. |
AlreadyBeingManaged | Thrown 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. |
AlreadyConnected | Thrown if addConnected is true and the host is already connected to vCenter. |
DuplicateName | Thrown if another host in the same folder has the name. |
GatewayConnectFault | Thrown if the host is managed via host gateway and any error occurred during the communication with the gateway |
GatewayHostNotReachable | Thrown if the host is managed via host gateway and the gateway server cannot connect to the host |
GatewayNotFound | Thrown if the host is managed via host gateway and no available gateway server is found for the given parameters |
GatewayNotReachable | Thrown 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 |
GatewayOperationRefused | Thrown if the gateway server cannot accept more host connections |
GatewayToHostAuthFault | Thrown if the host is managed via host gateway and the gateway server needs additional information to authenticate before the host |
GatewayToHostTrustVerifyFault | Thrown if the host is managed via host gateway and the gateway server cannot verify that the host is trusted |
HostConnectFault | Thrown if an error occurred when attempting to connect to a host. Typically, a more specific subclass, such as AlreadyBeingManaged, is thrown. |
InvalidLogin | Thrown if authentication with the host fails. |
NoHost | Thrown if the host cannot be contacted. |
NotSupportedHost | Thrown if the host is running a software version that is not supported. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
SSLVerifyFault | Thrown if the host certificate could not be authenticated |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
cluster P | ManagedObjectReference
to a ClusterComputeResource |
Specifies the cluster to which hosts need to be
added.
Since vSphere API 6.7.1 |
newHosts* P | FolderNewHostSpec[] |
Specifies a list of new hosts to be added to
the cluster. Hosts are first added as standalone hosts.
Since vSphere API 6.7.1 |
existingHosts* P | ManagedObjectReference[]
to a HostSystem[] |
Specifies a list of existing hosts to be
added to the cluster. Hosts are first moved to the desired state
before moving them to cluster.
Since vSphere API 6.7.1 |
compResSpec* P | ComputeResourceConfigSpec |
Specifies the configuration for the compute
resource that will be created to contain all the hosts.
Since vSphere API 6.7.1 |
desiredState* P | xsd:string |
Specifies desired state for hosts once added to
the cluster. If not specified, hosts are added to the cluster in their
current state. See FolderDesiredHostState for valid values.
Since vSphere API 6.7.1 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
In addition to the Host.Inventory.AddStandaloneHost privilege, the operation requires System.View privilege on the VM folder that the VMs of the host will be placed on.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
newHosts* P | FolderNewHostSpec[] |
Specifies a list of host specifications for new hosts.
Since vSphere API 6.7.1 |
compResSpec* P | ComputeResourceConfigSpec |
Specifies the configuration for the compute
resource that will be created to contain all the
hosts.
Since vSphere API 6.7.1 |
addConnected P | xsd:boolean |
Flag to specify whether or not hosts should be
connected at the time they are added. A host will not
be added if a connection attempt is made and fails.
Since vSphere API 6.7.1 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
name P | xsd:string |
Name for the new cluster.
Since 2.0 |
spec P | ClusterConfigSpec |
Specification for the cluster.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a ClusterComputeResource | A new ClusterComputeResource instance. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if an entity with that name already exists. |
InvalidName | Thrown if the name is not a valid entity name. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
name P | xsd:string |
Name for the new cluster.
Since VI API 2.5 |
spec P | ClusterConfigSpecEx |
Specification for the cluster.
Since VI API 2.5 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a ClusterComputeResource | A new ClusterComputeResource instance. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if an entity with that name already exists. |
InvalidName | Thrown if the name is not a valid entity name. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
name P | xsd: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.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Datacenter | A new Datacenter instance. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if an entity with that name already exists. |
InvalidName | Thrown if the new name is not a valid entity name. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
spec P | DVSCreateSpec |
The DVSCreateSpec
to create the distributed virtual switch.
Since vSphere API 4.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. After successful completion, the Task.Info.result property contains the newly registered DistributedVirtualSwitch. |
Faults
Type | Description |
---|---|
DuplicateName | |
DvsFault | |
DvsNotAuthorized | Thrown if login-session's extension key does not match (extensionKey). |
InvalidName | |
NotFound | |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
name P | xsd: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. Any percent (%)
character used in this parameter must be escaped, unless
it is used to start an escape sequence. Clients may also
escape any other characters in this parameter.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Folder | A reference to the new folder. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if another object in the same folder has the target name. |
InvalidName | Thrown if the name is not a valid entity name. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
name P | xsd:string |
Name for the new storage pod.
Since vSphere API 5.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a StoragePod | A new StoragePod instance. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if an entity with that name already exists. |
InvalidName | Thrown if the name is not a valid entity name. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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:
To create a VirtualNVDIMM device, the storage profile must be set to the default persistent memory storage profile while the datastore property of the device backing must be unset.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
config P | VirtualMachineConfigSpec |
The configuration of the virtual machine hardware.
Since 2.0 |
pool P | ManagedObjectReference
to a ResourcePool |
The resource pool to which the virtual machine will be attached.
Since 2.0 |
host* P | 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.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly created VirtualMachine upon success. |
Faults
Type | Description |
---|---|
AlreadyExists | Thrown if the requested cfgPath (or the default cfgPath) for the virtual machine's configuration file is already loaded in the inventory. |
DuplicateName | Thrown if another virtual machine in the same folder already has the specified target name. |
FileAlreadyExists | Thrown if the requested cfgPath for the virtual machine's configuration file already exists. |
FileFault | Thrown if there is a problem creating the virtual machine on disk. Typically, a more specific subclass, such as NoDiskSpace, will be thrown. |
InsufficientResourcesFault | Thrown if this operation would violate a resource usage policy. |
InvalidDatastore | Thrown if the operation cannot be performed on the target datastores. |
InvalidName | Thrown if the name is not a valid entity name. |
InvalidState | Thrown if the operation is not allowed in current state of the entities involved. |
OutOfBounds | Thrown if Host.capability.maxSupportedVMs is exceeded. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | Thrown if the configSpec has incorrect values. Typically, a more specific subclass is thrown. |
VmWwnConflict | Thrown if the WWN of the virtual machine has been used by other virtual machines. |
Events
Type | |
---|---|
None |
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:
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
list P | ManagedObjectReference[]
to a ManagedEntity[] |
The list of objects to be moved into the folder.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if this folder already contains an object with the specified name. |
InvalidFolder | Thrown if a Folder that is a parent of this Folder is part of the list of objects. |
InvalidState | Thrown if a HostSystem is not part of the same datacenter, not part of a ClusterComputeResource, or not in maintenance mode. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmAlreadyExistsInDatacenter | Thrown 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. |
Events
Type | |
---|---|
None |
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. In addition to the VirtualMachine.Inventory.Register and Resource.AssignVMToPool privileges, it requires System.Read privilege on the datastore that the existing virtual machine resides on. If the virtual machine is encrypted Cryptographer.RegisterVM is required on the folder, in which the virtual machine is registered. Otherwise, the VM is registered successfully, but is left in the locked state.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the Folder used to make the method call. |
path P | xsd:string |
A datastore path to the virtual machine.
Since 2.0 |
name* P | 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.
Since 2.0 |
asTemplate P | xsd:boolean |
Flag to specify whether or not the virtual machine
should be marked as a template.
Since 2.0 |
pool* P | ManagedObjectReference
to a ResourcePool |
The resource pool to which the virtual machine should be attached.
If imported as a template, this parameter is not set.
Since 2.0 |
host* P | 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,
the parameter can be omitted, and the system selects a default.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly registered VirtualMachine upon success. |
Faults
Type | Description |
---|---|
AlreadyExists | Thrown if the virtual machine is already registered. |
DuplicateName | Thrown if another virtual machine in the same folder has the target name. |
FileFault | Thrown if there is an error accessing the files on disk. |
InsufficientResourcesFault | Thrown if this operation would violate a resource usage policy. |
InvalidDatastore | Thrown if the operation cannot be performed on the target datastores. |
InvalidName | Thrown if the entity name is invalid. |
InvalidState | Thrown if the operation is not allowed in current state of the entities involved. |
NotFound | Thrown if the configuration file is not found on the system. |
OutOfBounds | Thrown if the maximum number of VMs for this folder has been exceeded. The maximum number is determined by Host.capability.maxSupportedVMs. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | Thrown 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. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | 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 |
---|---|
ConcurrentAccess | Thrown if another client modifies the folder contents before this operation completes. |
InvalidState | Thrown if a virtual machine is not powered off or suspended. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Top of page | Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |