Scripting Object - VcVirtualApp

Scripting-object corresponding to
VirtualApp
Parameter to
notifyPowerOn, retrievePublicOvfEnvironmentSections
Returned by
createVApp, createVApp, getAllVirtualApps, getAllVirtualApps

Scripting Object Description

Represents a multi-tiered software solution. A vApp is a collection of virtual machines (and potentially other vApp containers) that are operated and monitored as a unit. From a manage perspective, a multi-tiered vApp acts a lot like a virtual machine object. It has power operations, networks, datastores, and its resource usage can be configured.

From a technical perspective, a vApp container is a specialized resource pool that has been extended with the following capabilities:

  • Destroying a vApp

    When a vApp is destroyed, all of its virtual machines are destroyed, as well as any child vApps.

    The VApp.Delete privilege must be held on the vApp as well as the parent folder of the vApp. Also, the VApp.Delete privilege must be held on any child vApps that would be destroyed by the operation.

    Attributes

    Name Type Description
    alarmActionsEnabledBoolean

    @since vSphere API 4.0
    availableFieldVcCustomFieldDef []

    @since VI API 2.5
    childConfigurationVcResourceConfigSpec []

    @since VI API 2.5
    childLinkVcVirtualAppLinkInfo []

    @since vSphere API 4.1
    configVcResourceConfigSpec

    @since VI API 2.5
    configIssueVcEvent []

    @since VI API 2.5
    configStatusVcManagedEntityStatus

    @since VI API 2.5
    cpuReservationString

    @since Unknown
    customValueVcCustomFieldValue []

    @since VI API 2.5
    datastoreVcDatastore []

    @since vSphere API 4.0
    declaredAlarmStateVcAlarmState []

    @since VI API 2.5
    disabledMethodString []

    @since VI API 2.5
    effectiveRoleNumber []

    @since VI API 2.5
    idString

    @since Unknown
    memoryReservationString

    @since Unknown
    morefVcManagedObjectReference

    returns the ManagedObjectReference of this ManagedObject @since Unknown
    nameString

    @since VI API 2.5
    networkVcNetwork []

    @since vSphere API 4.0
    overallStatusVcManagedEntityStatus

    @since VI API 2.5
    ownerVcComputeResource

    @since VI API 2.5
    parentVcManagedEntity

    @since VI API 2.5
    parentFolderVcFolder

    @since vSphere API 4.0
    parentVAppVcManagedEntity

    @since vSphere API 4.1
    permissionVcPermission []

    @since VI API 2.5
    recentTaskVcTask []

    @since VI API 2.5
    resourcePoolVcResourcePool []

    @since VI API 2.5
    runtimeVcResourcePoolRuntimeInfo

    @since VI API 2.5
    sdkConnectionVcSdkConnection

    @since Unknown
    sdkIdString

    @since Unknown
    summaryVcResourcePoolSummary

    @since VI API 2.5
    tagVcTag []

    @since vSphere API 4.0
    triggeredAlarmStateVcAlarmState []

    @since VI API 2.5
    typeStringDeprecated.

    Returns the name for the this managed object's vim type @since Unknown
    valueVcCustomFieldValue []

    @since VI API 2.5
    vAppConfigVcVAppConfigInfo

    @since vSphere API 4.0
    vimHostVcSdkConnection

    @since Unknown
    vimIdString

    @since Unknown
    vimTypeString

    @since Unknown
    vmVcVirtualMachine []

    @since VI API 2.5

    Methods

    Methods defined in this Scripting Object
    _getRef, addTag, cloneVApp_Task, createChildVM_Task, createResourcePool, createTrigger, createVApp, destroy_Task, destroyChildren, exportVApp, importVApp, moveIntoResourcePool, powerOffVApp_Task, powerOnVApp_Task, queryResourceConfigOption, refreshRuntime, registerChildVM_Task, reload, removeTag, rename_Task, retrieveCustomValues, setCustomValue, suspendVApp_Task, unregisterVApp_Task, updateChildResourceConfiguration, updateConfig, updateLinkedChildren, updateVAppConfig

    createVApp

    Creates a new vApp container.

    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. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0String

    arg1VcResourceConfigSpec

    arg2VcVAppConfigSpec

    arg3VcFolder


    Return Value

    Type Description
    VcVirtualApp

    removeTag

    Removes a set of tags from this object. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0VcTag []


    Return Value

    Type Description
    None

    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. @since VI API 2.5

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcTask

    createResourcePool

    Creates a new resource pool.

    In the ResourceConfigSpec, all values in ResourceAllocationInfo must be supplied; they are not optional.

    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. @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0String

    arg1VcResourceConfigSpec


    Return Value

    Type Description
    VcResourcePool

    refreshRuntime

    Refreshes the resource usage data that is available in {@link ResourcePool.RuntimeInfo}. The latest runtime resource usage of this resource pool may not be available immediately after operations that alter resource usage, such as powering on a virtual machine. Invoke this method when resource usage may have recently changed, and the most up-to-date value in the {@link ResourcePool.RuntimeInfo} is needed. @since vSphere API 4.1

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    None

    createTrigger

    @since Unknown

    Parameters

    NameTypeDescription
    timeoutNumber

    filterString

    conditionString

    filterToSyncString


    Return Value

    Type Description
    Trigger

    registerChildVM_Task

    Adds an existing virtual machine to this resource pool or vApp.

    This operation only works for vApps or resource pools that are children of vApps. To register a VM in a folder, see {@link vim.Folder#registerVm}.

    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. In addition to the VirtualMachine.Inventory.Register privilege, it requires System.Read privilege on the datastore that the existing virtual machine resides on. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0String

    arg1String

    arg2VcHostSystem


    Return Value

    Type Description
    VcTask

    createChildVM_Task

    Creates a new virtual machine in a vApp container.

    This method supports creating a virtual machine directly in a vApp. A virtual machine in a vApp is not associated with a VM folder and therefore cannot be created using the method on a {@link vim.Folder#createVm Folder}.

    This method can only be called directly on a {@link vim.VirtualApp vApp} or on a resource pool that is a child of a vApp.

    The privilege VirtualMachine.Inventory.Create is required on this entity. Further, if this is a resource pool, the privilege Resource.AssignVMToPool is required. If this is a vApp, the privilege VApp.AssignVM is required.

    Depending on the properties of the virtual machine bring created, additional privileges may be required. See {@link vim.Folder#createVm} for a description of these privileges. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0VcVirtualMachineConfigSpec

    arg1VcHostSystem


    Return Value

    Type Description
    VcTask

    _getRef

    @since Unknown

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcManagedObjectReference

    updateConfig

    Updates the configuration of the resource pool.

    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.

    The privilege checks for this operation are as follows:

    @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0String

    arg1VcResourceConfigSpec


    Return Value

    Type Description
    None

    updateChildResourceConfiguration

    Changes resource configuration of a set of children of this resource pool. The method allows bulk modifications of the set of the direct children (virtual machines and resource pools).

    Bulk modifications are not transactional. Each modification is made individually. If a failure is encountered while applying the changes, then the processing stops, meaning at least one and as many as all of the changes are not applied.

    A set can include a subset of the resources. Children that are not mentioned in the list are not changed.

    For each ResourceConfigSpec, the following privilege checks apply:

    @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0VcResourceConfigSpec []


    Return Value

    Type Description
    None

    destroyChildren

    Removes all child resource pools recursively. All virtual machines and vApps associated with the child resource pools get associated with this resource pool.

    Note that resource pools contained in child vApps are not affected.

    The privilege checks performed are the following.

    @since VI API 2.5

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    None

    moveIntoResourcePool

    Moves a set of resource pools, vApps or virtual machines into this pool. The pools, vApps and virtual machines must be part of the cluster or standalone host that contains this pool.

    For each entity being moved, the move is subject to the following privilege checks:

    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 only transactional 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 a failure is detected, then the method terminates with an exception.

    The root resource pool cannot be moved. @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0VcManagedEntity []


    Return Value

    Type Description
    None

    powerOffVApp_Task

    Stops this vApp.

    The virtual machines (or child vApps) will be stopped in the order specified in the vApp configuration, if force is false. If force is set to true, all virtual machines are powered-off (in no specific order and possibly in parallel) regardless of the vApp auto-start configuration.

    While a vApp is stopping, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0Boolean


    Return Value

    Type Description
    VcTask

    cloneVApp_Task

    Creates a clone of this vApp.

    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.

    When invoking this method, the following privilege checks occur:

    Additional privileges are required by the clone spec provided. See {@link vim.vApp.CloneSpec} for details. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0String

    arg1VcResourcePool

    arg2VcVAppCloneSpec


    Return Value

    Type Description
    VcTask

    exportVApp

    Obtains an export lease on this vApp. The export lease contains a list of URLs for the disks of the virtual machines in this vApp, as well as a ticket that gives access to these URLs.

    See {@link vim.HttpNfcLease} for information on how to use the lease. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcHttpNfcLease

    setCustomValue

    Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the {@link CustomFieldsManager.FieldDef#fieldInstancePrivileges} for the CustomFieldDef whose value is being changed. @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0String

    arg1String


    Return Value

    Type Description
    None

    powerOnVApp_Task

    Starts this vApp.

    The virtual machines (or sub vApps) will be started in the order specified in the vApp configuration. If the vApp is suspended (@see vim.VirtualApp.Summary.suspended), all suspended virtual machines will be powered-on based on the defined start-up order.

    While a vApp is starting, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress.

    In case of a failure to power-on a virtual machine, the exception from the virtual machine power on is returned, and the power-on sequence will be terminated. In case of a failure, virtual machines that are already started will remain powered-on.

    @since vSphere API 4.0

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcTask

    importVApp

    Creates a new entity in this resource pool. The import process consists of two steps:
    1. Create the VMs and/or vApps that make up the entity.
    2. Upload virtual disk contents.
    In step 1, the client must wait for the server to create all inventory objects. It does that by monitoring the {@link vim.HttpNfcLease#state} property on the {@link vim.HttpNfcLease} object returned from this call. When the server is done creating objects, the lease will change to the ready state, and step 2 begins. If an error occurs while the server is creating inventory objects, the lease will change to the error state, and the import process is aborted.

    In step 2, the client uploads disk contents using the URLs provided in the {@link vim.HttpNfcLease#info} property of the lease. The client must call {@link vim.HttpNfcLease#progress} on the lease periodically to keep the lease alive and report progress to the server. Failure to do so will cause the lease to time out, and the import process will be aborted.

    When the client is done uploading disks, it completes the lease by calling {@link vim.HttpNfcLease#complete}. The client can also abort the import process by calling {@link vim.HttpNfcLease#abort}.

    If the import process fails, is aborted, or times out, all created inventory objects are removed, including all virtual disks.

    This operation only works if the folder's childType includes VirtualMachine.

    Depending on the properties of the virtual machine bring imported, additional privileges may be required. See {@link vim.Folder#createVm} for a description of these privileges. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0VcImportSpec

    arg1VcFolder

    arg2VcHostSystem


    Return Value

    Type Description
    VcHttpNfcLease

    unregisterVApp_Task

    Removes this vApp from the inventory without removing any of the virtual machine's files on disk. All high-level information stored with the management server (ESX Server or VirtualCenter) is removed, including information such as vApp configuration, statistics, permissions, and alarms.

    @since vSphere API 4.0

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcTask

    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. @since VI API 2.5

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    None

    retrieveCustomValues

    Retrieve Custom field values based on specified custom field keys. If there is no key specified, all custom values associated to this ManagedEntity will be returned. @since vSphere API 6.5

    Parameters

    NameTypeDescription
    arg0Number []


    Return Value

    Type Description
    VcCustomFieldValue []

    queryResourceConfigOption

    Get a value range and default values for {@link ResourceConfigSpec}. @since vSphere API 4.1

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcResourceConfigOption

    updateVAppConfig

    Updates the vApp configuration.

    Updates in different areas require different privileges. See {@link vim.vApp.VAppConfigSpec} for a full description. @since vSphere API 4.0

    Parameters

    NameTypeDescription
    arg0VcVAppConfigSpec


    Return Value

    Type Description
    None

    suspendVApp_Task

    Suspends this vApp.

    Suspends all powered-on virtual machines in a vApp, including virtual machines in child vApps. The virtual machines are suspended in the same order as used for a power-off operation (reverse power-on sequence).

    While a vApp is being suspended, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress. @since vSphere API 4.1

    Parameters

    NameTypeDescription
    None

    Return Value

    Type Description
    VcTask

    updateLinkedChildren

    Reconfigure the set of linked children.

    A VirtualMachine and vApp can be added as a linked child as long as it is not a direct child of another vApp. In case it is a linked child, the existing link is removed and replaced with the new link specified in this call.

    An InvalidArgument fault is thrown if a link target is a direct child of another vApp, or if the addition of the link will result in a vApp with a cycle. For example, a vApp cannot be linked to itself.

    The removeSet must refer to managed entities that are currently linked children. Otherwise, an InvalidArgument exception is thrown.

    For each entity being linked, the operation is subject to the following privilege checks:

    Privilege checks for each entity in the removeSet are similar to the entities in the addChangeSet, except that there is no target vApp.

    This operation is only transactional with respect to each individual link change. The changes are processed sequentially and committed one at a time. The addChangeSet is processed first, followed by the removeSet. If a failure is detected, then the method terminates with an exception. @since vSphere API 4.1

    Parameters

    NameTypeDescription
    arg0VcVirtualAppLinkInfo []

    arg1VcManagedEntity []


    Return Value

    Type Description
    None

    addTag

    Add a set of tags to this object that can be queried later. The tag must be of the form "system/" or "global/ Parameters

    NameTypeDescription
    arg0VcTag []


    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.

    @since VI API 2.5

    Parameters

    NameTypeDescription
    arg0String


    Return Value

    Type Description
    VcTask