Managed Object - Folder

Property of: Datacenter, FolderEventArgument, HostConnectSpec, ServiceContent
Parameter to: CloneVM_Task
Returned by: CreateFolder
Extends: ManagedEntity
See also: ClusterComputeResource, ClusterConfigSpec, ClusterConfigSpecEx, ComputeResource, ComputeResourceConfigSpec, Datacenter, HostConnectSpec, HostSystem, ManagedEntity, ResourcePool, VirtualMachine, VirtualMachineConfigSpec

Managed Object Description

These are generic folders for storing inventory objects.

Both a folder's type and the objects it may contain are determined by a folder's childType property.

This managed object also acts as a factory object, meaning it creates new entities in a folder.

Calling "destroy" on a folder recursively removes all child objects and folders. The "destroy" operation is transactional only with respect to each individual entity being removed. During the "destroy" operation, the system recursively traverses the hierarchy and calls "destroy" on each object, committing each call individually. If the destroy call fails on an object, the method terminates at that point with an exception, leaving some or all of the objects still in the inventory.

Calling "destroy" on a virtual machine folder recursively calls "destroy" on all the child virtual machines, which are then removed from disk. Use UnregisterAndDestroy to unregister virtual machines recursively without removing them from the disk.

Destroying a host folder or datacenter folder unregisters all child hosts and virtual machines from VirtualCenter. The hosts are simply removed from the inventory, along with their virtual machines. The virtual machines are not removed from disk nor are their runtime states changed.

The root host folder and virtual machine folder of a datacenter cannot be destroyed, renamed, or moved.

Properties

Name	Type	Description
childEntity* P	ManagedObjectReference[] to a ManagedEntity[]	List of child entities. The types of entities that are allowed as child entities are specified by the property childType.
childType* P	xsd:string[]	The childType property specifies the object types a folder may contain. All folders may contain two things: other folders and one other type of object. The other type of object may be of type Datacenter, VirtualMachine (which includes templates), or ComputeResource. By prescribing acceptable childType values, the system encourages a logical organization of objects and relationships. For example, any folder outside of a datacenter has childType values of "Folder" and "Datacenter". This is sensible because it allows the folder to contain other Folder and Datacenter objects, but it prevents objects such as ComputeResource or VirtualMachine, which should not exist outside of datacenters, from being created there. While childType values help create a workable object hierarchy, they can also be used to deduce a relative position of a folder in a collection of objects. If a folder includes the childType value "Datacenter", the folder may contain other folders and datacenters. This folder may be contained by other folders outside of a datacenter. The folder is probably closer to the top of its inventory tree. If a folder includes the childType value "VirtualMachine", the folder may contain other folders and virtual machines. This folder is contained by a datacenter or other folders within a datacenter. If a folder includes the childType value "ComputeResource", the folder may contain other folders and compute resources. The childType property is an array that contains a set of strings. For example: The root folder and its descendant folders would have: childType = { "vim.Folder", "vim.Datacenter" } A data center's host folder and its descendant folders would have: childType = { "vim.Folder", "vim.ComputeResource" } A data center's vm folder and its descendant folders would have: childType = { "vim.Folder", "vim.Virtualmachine" } A folder that is a subfolder of another folder inherits the childType values from its parent folder.
Properties inherited from ManagedEntity
configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, 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, 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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
spec	HostConnectSpec	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
addConnected	xsd: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.

*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
AgentInstallFailed	Thrown if there is an error installing the VirtualCenter agent on the new host.
AlreadyBeingManaged	Thrown if the host is already being managed by a VirtualCenter server. If the host is being managed by a different VirtualCenter 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 VirtualCenter.
HostConnectFault	Thrown if an error occurred when attempting to connect to a host. Typically, a more specific subclass, such as AlreadyBeingManaged, is thrown.
InvalidArgument	Thrown if an argument is specified incorrectly.
InvalidLogin	Thrown if authentication with the host fails.
NoHost	Thrown if the host cannot be contacted.
NotEnoughLicenses	Thrown if there are not enough licenses to add the host.
NotSupported	Thrown if the host is being added to a folder whose childType property does not contain "ComputeResource".
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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddStandaloneHost" type="vim25:AddStandaloneHostRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddStandaloneHostResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
name	xsd:string	Name for the new cluster.
spec	ClusterConfigSpec	Specification for the cluster.

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.
InvalidArgument	Thrown if the cluster configuration specification parameter is invalid.
InvalidName	Thrown if the name is not a valid entity name.
NotSupported	Thrown if the cluster is being added to a folder whose childType property value does not contain "ComputeResource" or "ClusterComputeResource".
RuntimeFault	Thrown 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

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateCluster" type="vim25:CreateClusterRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateClusterResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
name	xsd:string	Name for the new cluster.
spec	ClusterConfigSpecEx	Specification for the cluster.

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.
InvalidArgument	Thrown if the cluster configuration specification parameter is invalid.
InvalidName	Thrown if the name is not a valid entity name.
NotSupported	Thrown if the cluster is being added to a folder whose childType property value does not contain "ComputeResource" or "ClusterComputeResource".
RuntimeFault	Thrown 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

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateClusterEx" type="vim25:CreateClusterExRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateClusterExResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
name	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.

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.
NotSupported	Thrown if the datacenter is being created within a folder whose childType property value does not contain "Datacenter".
RuntimeFault	Thrown 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

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateDatacenter" type="vim25:CreateDatacenterRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateDatacenterResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
name	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.

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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFolder" type="vim25:CreateFolderRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFolderResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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, templates should be created 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:

VirtualMachine.Config.AddExistingDisk if including a virtual disk device that refers to an existing virtual disk file (not RDM)
VirtualMachine.Config.AddNewDisk if including a virtual disk device that creates a new virtual disk file (not RDM)
VirtualMachine.Config.RawDevice if including a raw device mapping (RDM) or SCSI passthrough device
VirtualMachine.Config.HostUSBDevice if including a VirtualUSB device backed by a host USB device
VirtualMachine.Config.AdvancedConfig if setting values in ConfigSpec.extraConfig
VirtualMachine.Config.SwapPlacement if setting swapPlacement

Required Privileges: VirtualMachine.Inventory.Create

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
config	VirtualMachineConfigSpec	The configuration of the virtual machine hardware.
pool P	ManagedObjectReference 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
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.
NotSupported	Thrown if the virtual machine is being created within a folder whose childType property is not set to "VirtualMachine".
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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateVM" type="vim25:CreateVMRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateVMResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Folder.Move if the object is a Folder
Datacenter.Move if the object is a Datacenter
Host.Inventory.MoveCluster if the object is a ComputeResource
VirtualMachine.Inventory.Move if the object is a virtual machine or virtual machine template

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

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
list	ManagedObjectReference[] 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
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.
NotSupported	Thrown 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".
RuntimeFault	Thrown 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

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="MoveIntoFolder" type="vim25:MoveIntoFolderRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="MoveIntoFolderResponse">
            <complexType/>
         </element>

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

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the Folder used to make the method call.
path	xsd: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.
asTemplate	xsd:boolean	Flag to specify whether or not the virtual machine should be marked as a template.
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.
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
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.
InvalidArgument	Thrown if any of the arguments such as host or resource pool are not set to valid values.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidName	Thrown if the entity name is invalid.
NotFound	Thrown if the configuration file is not found on the system.
NotSupported	Thrown 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".
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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RegisterVM" type="vim25:RegisterVMRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RegisterVMResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

UnregisterAndDestroy_Task

Recursively unregisters all virtual machines and destroys all child virtual machine folders. This is similar to the "destroy" method, but unregisterAndDestroy calls "unregister" on each virtual machine object instead of "destroy". This operation applies only to VirtualMachine folders.

This operation is transactional only with respect to each individual virtual machine being unregistered or folder being destroyed. The system recursively traverses the hierarchy and calls "unregister" on each virtual machine object and "destroy" on each child virtual machine folder, committing each transaction individually. If a failure occurs, the method terminates at that point with an exception, leaving some or all objects unaffected.

This method also requires the VirtualMachine.Delete privilege to be held on the folder as well as the virtual machines.

Required Privileges: Folder.Delete

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.
NotSupported	Thrown if the childType property of the folder is not set to "VirtualMachine".
RuntimeFault	Thrown 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

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UnregisterAndDestroy" type="vim25:UnregisterAndDestroyRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UnregisterAndDestroyResponse">
            <complexType/>
         </element>