Scripting Object - VcFolder

Scripting-object corresponding to
DatacenterFolder
Attribute of
_VcPlugin, VcDatacenter, VcFolderEventArgument, VcHostConnectSpec, VcSdkConnection, VcServiceContent, VcVAppCloneSpec, VcVirtualApp
Parameter to
cloneVM_Task, createVApp, createVApp, importVApp, importVApp
Returned by
createFolder, getAllDatacenterFolders, getAllDatacenterFolders, getAllDatastoreFolders, getAllDatastoreFolders, getAllHostFolders, getAllHostFolders, getAllNetworkFolders, getAllNetworkFolders, getAllVmFolders, getAllVmFolders

Scripting Object Description

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

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

VcFolder inherits the VcManagedEntity method. VcManagedEntity is a recursive operation that removes all child objects and folders. When you call VcManagedEntity to destroy a folder, the system uses the specified folder as a root and traverses its descendant hierarchy, calling VcManagedEntity on each object. VcManagedEntity is a single operation that treats each recursive call as a single transaction, committing each call to remove an object individually. If VcManagedEntity 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:

Attributes

Name Type Description
alarmActionsEnabled*boolean

Whether alarm actions are enabled for this entity. True if enabled; false otherwise.
availableField*VcCustomFieldDef []

List of custom field definitions that are valid for the object's type. The fields are sorted by VcCustomFieldDef.
childEntity*VcManagedEntity []

An array of managed object references. Each entry is a reference to a child entity.
childType*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.
clusterComputeResourceClusterComputeResource []

Filtered attribute 'computeResource' with only ClusterComputeResource objects (depracated)
computeResourceComputeResource []

Filtered attribute 'computeResource' with only ComputeResource objects (depracated)
computeResource_ClusterComputeResourceClusterComputeResource []

Filtered attribute 'computeResource' with only ClusterComputeResource objects
computeResource_ComputeResourceComputeResource []

Filtered attribute 'computeResource' with only ComputeResource objects
configIssue*VcEvent []

Current configuration issues that have been detected for this entity. Typically, these issues have already been logged as events. The entity stores these events as long as they are still current. The VcManagedEntity property provides an overall status based on these events.
configStatusVcManagedEntityStatus

The configStatus indicates whether or not the system has detected a configuration issue involving this entity. For example, it might have detected a duplicate IP address or MAC address, or a host in a cluster might be out of compliance. The meanings of the configStatus values are:
  • red: A problem has been detected involving the entity.
  • yellow: A problem is about to occur or a transient condition has occurred (For example, reconfigure fail-over policy).
  • green: No configuration issues have been detected.
  • gray: The configuration status of the entity is not being monitored.
A green status indicates only that a problem has not been detected; it is not a guarantee that the entity is problem-free.

The VcManagedEntity property contains a list of the problems that have been detected.

customValue*VcCustomFieldValue []

Custom field values.
declaredAlarmState*VcAlarmState []

A set of alarm states for alarms that apply to this managed entity. The set includes alarms defined on this entity and alarms inherited from the parent entity, or from any ancestors in the inventory hierarchy.

Alarms are inherited if they can be triggered by this entity or its descendants. This set does not include alarms that are defined on descendants of this entity.

disabledMethod*string []

List of operations that are disabled, given the current runtime state of the entity. For example, a power-on operation always fails if a virtual machine is already powered on. This list can be used by clients to enable or disable operations in a graphical user interface.

Note: This list is determined by the current runtime state of an entity, not by its permissions.

This list may include the following operations for a HostSystem:

This list may include the following operations for a VirtualMachine:

This list may include the following operations for a ResourcePool:

This list may include the following operations for a VirtualApp:

distributedVirtualSwitch_DistributedVirtualSwitchDistributedVirtualSwitch []

Filtered attribute 'distributedVirtualSwitch' with only DistributedVirtualSwitch objects
distributedVirtualSwitch_VmwareDistributedVirtualSwitchVmwareDistributedVirtualSwitch []

Filtered attribute 'distributedVirtualSwitch' with only VmwareDistributedVirtualSwitch objects
effectiveRole*number []

Access rights the current session has to this entity.
idstring

returns the id of this ManagedObject
namestring

Name of this entity, unique relative to its parent.

Any / (slash), \ (backslash), character used in this name element will be escaped. Similarly, any % (percent) character used in this name element will be escaped, unless it is used to start an escape sequence. A slash is escaped as %2F or %2f. A backslash is escaped as %5C or %5c, and a percent is escaped as %25.

network_DistributedVirtualPortgroupDistributedVirtualPortgroup []

Filtered attribute 'network' with only DistributedVirtualPortgroup objects
network_NetworkNetwork []

Filtered attribute 'network' with only Network objects
overallStatusVcManagedEntityStatus

General health of this managed entity. The value combines the status of all the alarms attached to a managed entity.

If any of the alarms has a gray status, the overall status of the managed entity is gray. Otherwise, if any of the alarms has a red status, the overall status of the managed entity is red. Otherwise, if any of the alarms has a yellow status, the overall status of the managed entity is yellow. Otherwise, the overall status of the managed entity is green.

parent*VcManagedEntity

Parent of this entity.

This value is null for the root object.

permission*VcPermission []

List of permissions defined for this entity.
recentTask*VcTask []

The set of recent tasks operating on this managed entity. This is a subset of VcTaskManager belong to this entity. A task in this list could be in one of the four states: pending, running, success or error.

This property can be used to deduce intermediate power states for a virtual machine entity. For example, if the current powerState is "poweredOn" and there is a running task performing the "suspend" operation, then the virtual machine's intermediate state might be described as "suspending."

Most tasks (such as power operations) obtain exclusive access to the virtual machine, so it is unusual for this list to contain more than one running task. One exception, however, is the task of cloning a virtual machine.

referenceVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject
resourcePool_ResourcePoolResourcePool []

Filtered attribute 'resourcePool' with only ResourcePool objects
resourcePool_VirtualAppVirtualApp []

Filtered attribute 'resourcePool' with only VirtualApp objects
sdkConnectionVcSdkConnection

returns the parent SdkConnection
tag*VcTag []

The set of tags associated with this managed entity. Experimental. Subject to change.
triggeredAlarmState*VcAlarmState []

A set of alarm states for alarms triggered by this entity or by its descendants.

Triggered alarms are propagated up the inventory hierarchy so that a user can readily tell when a descendant has triggered an alarm.

value*VcCustomFieldValue []

List of custom field values. Each value uses a key to associate an instance of a VcCustomFieldStringValue with a custom field definition.
vimHostVcSdkConnection

returns the parent SdkConnection (deprecated)
vimTypestring

returns the type of this ManagedObject
*May not be present

Methods

Methods defined in this Scripting Object
addStandaloneHost_Task, createCluster, createClusterEx, createDatacenter, createDVS_Task, createFolder, createTrigger, createVM_Task, destroy_Task, moveIntoFolder_Task, registerVM_Task, reload, rename_Task, setCustomValue, unregisterAndDestroy_Task

reload

Reload the entity state. Clients only need to call this method if they changed some external state that affects the service without using the Web service interface to perform the change. For example, hand-editing a virtual machine configuration file affects the configuration of the associated virtual machine but the service managing the virtual machine might not monitor the file for changes. In this case, after such an edit, a client would call "reload" on the associated virtual machine to ensure the service and its clients have current data for the virtual machine.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

rename_Task

Renames this managed entity.

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.


See VcManagedEntity

Parameters

NameTypeDescription
newNamestring


See VcManagedEntity

Return Value

Type Description
VcTask

destroy_Task

Destroys this object, deleting its contents and removing it from its parent folder (if any).

NOTE: The appropriate privilege must be held on the parent of the destroyed entity as well as the entity itself.

This method can throw one of several exceptions. The exact set of exceptions depends on the kind of entity that is being removed. See comments for each entity for more information on destroy behavior.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

setCustomValue

Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the VcCustomFieldDef for the CustomFieldDef whose value is being changed.

Parameters

NameTypeDescription
keystring

The name of the field whose value is to be updated.
valuestring

Value to be assigned to the custom field.

Return Value

Type Description
None

createFolder

Creates a new sub-folder with the specified name. The VcFolder property of the new folder is the same as the VcFolder 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.

Parameters

NameTypeDescription
namestring

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
VcFolder

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

Parameters

NameTypeDescription
listVcManagedEntity []

The list of objects to be moved into the folder.

Return Value

Type Description
VcTask

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:

Parameters

NameTypeDescription
configVcVirtualMachineConfigSpec

The configuration of the virtual machine hardware.
poolVcResourcePool

The resource pool to which the virtual machine will be attached.
host*VcHostSystem

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

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
pathstring

A datastore path to the virtual machine.
name*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.
asTemplateboolean

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

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

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

Return Value

Type Description
VcTask

createCluster

Deprecated.

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.

Parameters

NameTypeDescription
namestring

Name for the new cluster.
specVcClusterConfigSpec

Specification for the cluster.

Return Value

Type Description
VcClusterComputeResource

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.

Parameters

NameTypeDescription
namestring

Name for the new cluster.
specVcClusterConfigSpecEx

Specification for the cluster.

Return Value

Type Description
VcClusterComputeResource

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.

Parameters

NameTypeDescription
specVcHostConnectSpec

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

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

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*string

Provide a licenseKey or licenseKeyType. See VcLicenseManager
*Need not be set

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
namestring

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
VcDatacenter

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

createDVS_Task

Create a Distributed Virtual Switch in the folder according to the specified (@link vim.DistributedVirtualSwitch.CreateSpec).

Parameters

NameTypeDescription
specVcDVSCreateSpec

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

Return Value

Type Description
VcTask

createTrigger

Create a trigger from this ManagedObject

Parameters

NameTypeDescription
timeoutnumber

Waiting timout in seconds
filterstring

The monitored vCenter API filter
conditionstring

The condition in OGNL language
filterToSync*string

The vCenter API filter used to synchronize the content of the session
*Need not be set

Return Value

Type Description
Trigger