Citrix Virtual Apps and Desktops SDK

Import-ProvVM

Introduced in: Citrix Virtual Apps and Desktop 7 2311

Import provisioning virtual machines under the given provisioning scheme.

Syntax

Import-ProvVM
      [-ProvisioningSchemeName <String>]
      -ProvisioningVirtualMachineData <String>
      [-LoggingId <Guid>]
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->
Import-ProvVM
      [-ProvisioningSchemeUid <Guid>]
      -ProvisioningVirtualMachineData <String>
      [-LoggingId <Guid>]
      [<CitrixCommonParameters>]
      [<CommonParameters>]
<!--NeedCopy-->

Description

This cmdlet reads the list of provisioning virtual machines (VMs) of a given provisioning scheme and imports them to the database. The list of VMs can be obtained from the output of the Export-ProvScheme cmdlet. If a VM in the list already exists in the database, it will fail silently. If the provisioning scheme the VM is associated with does not exist, it will return an error. This cmdlet returns a list of VM objects imported successfully.

Examples

EXAMPLE 1

Import the JSON encoded provisioning virtual machines that is in $ExportedProvVMs

Import-ProvVM -ProvisioningSchemeName ExampleCatalog -provisioningVirtualMachineData $ExportedProvVMs

FailureReason                                  : The VM already exists
ImportStatus                                   : Failed
WindowsActivationStatusVirtualMachineError     : The information is currently unavailable
ADAccountName                                  :
ADAccountSid                                   : S-1-5-21-1369695582-2951410066-511316603-44756
CpuCount                                       : 1
CreationDate                                   : 7/21/2023 11:47:32 AM
Domain                                         : serenity.local
ImageOutOfDate                                 : False
Lock                                           : False
MemoryMB                                       : 256
PVSDeviceId                                    :
PropertyUpdateWindowEnd                        :
PropertyUpdateWindowStart                      :
ProvVMConfigurationVersion                     :
ProvisioningSchemeName                         : ExampleCatalog
ProvisioningSchemeUid                          : bd9b4150-1d02-47b4-82ba-017f7d6e8a19
ProvisioningSchemeVersion                      : 1
Tag                                            :
VMId                                           : bd475e5c-f296-54ea-59a4-9cff1b9269aa
VMName                                         : HaanVM128
WindowsActivationStatus                        : Unknown
WindowsActivationStatusErrorCode               : Unknown
WindowsActivationTypeProvisionedVirtualMachine : UnsupportedVDA
AssignedImage                                  : bda00c96-6e3b-44f0-931a-7afeb1ed5371
BootedImage                                    : bda00c96-6e3b-44f0-931a-7afeb1ed5371
HostingUnitUid                                 : ec3f578e-d7b2-4a83-b3c9-d334798e1448
HypervisorConnectionUid                        : ec3f578e-d7b2-4a83-b3c9-d334798e1448
IdentityDiskIndex                              : 1
LastBootTime                                   : 7/21/2023 11:47:32 AM
OSDiskIndex                                    : 0
PersonalVDiskIndex                             : -1
PersonalVDiskStorage                           :
StorageId                                      : 83d77270-8116-1b72-71b8-b4b4b5e4e1b2
NetworkMaps                                    : {}
IdentityDiskId                                 : 3b37074f-4fdc-4de5-9bff-374dfbbc2639
IdentityDiskStorage                            : 83d77270-8116-1b72-71b8-b4b4b5e4e1b2
PersonalVDiskId                                :
SecurityGroups                                 : {}
AdditionalStorage                              : {}
UseFullDiskCloneProvisioning                   : False
WriteBackCacheMemorySize                       : 0
CustomVmData                                   :
WorkgroupMachine                               : False

FailureReason                                  :
ImportStatus                                   : Success
WindowsActivationStatusVirtualMachineError     : The information is currently unavailable
ADAccountName                                  :
ADAccountSid                                   : S-1-5-21-1369695582-2951410066-511316603-44761
CpuCount                                       : 1
CreationDate                                   : 7/21/2023 11:47:32 AM
Domain                                         : serenity.local
ImageOutOfDate                                 : False
Lock                                           : False
MemoryMB                                       : 256
PVSDeviceId                                    :
PropertyUpdateWindowEnd                        :
PropertyUpdateWindowStart                      :
ProvVMConfigurationVersion                     :
ProvisioningSchemeName                         : ExampleCatalog
ProvisioningSchemeUid                          : bd9b4150-1d02-47b4-82ba-017f7d6e8a19
ProvisioningSchemeVersion                      : 1
Tag                                            :
VMId                                           : fbe4a32a-adb6-52a8-6850-974e67a0eb3f
VMName                                         : HaanVM129
WindowsActivationStatus                        : Unknown
WindowsActivationStatusErrorCode               : Unknown
WindowsActivationTypeProvisionedVirtualMachine : UnsupportedVDA
AssignedImage                                  : bda00c96-6e3b-44f0-931a-7afeb1ed5371
BootedImage                                    : bda00c96-6e3b-44f0-931a-7afeb1ed5371
HostingUnitUid                                 : ec3f578e-d7b2-4a83-b3c9-d334798e1448
HypervisorConnectionUid                        : ec3f578e-d7b2-4a83-b3c9-d334798e1448
IdentityDiskIndex                              : 1
LastBootTime                                   : 7/21/2023 11:47:32 AM
OSDiskIndex                                    : 0
PersonalVDiskIndex                             : -1
PersonalVDiskStorage                           :
StorageId                                      : 83d77270-8116-1b72-71b8-b4b4b5e4e1b2
NetworkMaps                                    : {}
IdentityDiskId                                 : f18788ac-053d-4d9d-9093-181a2bc66d06
IdentityDiskStorage                            : 83d77270-8116-1b72-71b8-b4b4b5e4e1b2
PersonalVDiskId                                :
SecurityGroups                                 : {}
AdditionalStorage                              : {}
UseFullDiskCloneProvisioning                   : False
WriteBackCacheMemorySize                       : 0
CustomVmData                                   :
WorkgroupMachine                               : False
<!--NeedCopy-->

Parameters

-ProvisioningVirtualMachineData

JSON encoded string of VMs created with the provisioning scheme

Type: String
Position: Named
Default value: None
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True

-ProvisioningSchemeName

The name of the provisioning scheme.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True

-ProvisioningSchemeUid

The unique identifier of the provisioning scheme.

Type: Guid
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

-LoggingId

Specifies the identifier of the high-level operation this cmdlet call forms a part of. Citrix Studio and Director typically create high-level operations. PowerShell scripts can also wrap a series of cmdlet calls in a high-level operation by way of the Start-LogHighLevelOperation and Stop-LogHighLevelOperation cmdlets.

Type: Guid
Position: Named
Default value: None
Required: False
Accept pipeline input: False
Accept wildcard characters: False

CitrixCommonParameters

This cmdlet supports the common Citrix parameters: -AdminAddress, -AdminClientIP, -BearerToken, -TraceParent, -TraceState and -VirtualSiteId. For more information, see about_CitrixCommonParameters.

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

None

You can’t pipe objects to this cmdlet.

Outputs

Citrix.MachineCreation.Sdk.ImportProvVmModel

The returned objects provides details of the provisioning virtuam machines and contains the following information.

FailureReason <string> The reason for the failure of importing the VM.

ImportStatus <string> The status of the imported VM.

ADAccountName <string> The name of the AD computer account that the VM is using.

ADAccountSid <string> The SID of the AD computer account that the VM is using.

CpuCount <int> The number of processors allocated to the VM.

CreationDate <DateTime> The date and time when the VM was created.

Domain <string> The Domain of the AD computer account that the VM is using.

ImageOutOfDate <bool> Indicates if the image will be updated next time the VM is started.

Lock <bool> Indicates whether the VM is locked or not.

MemoryMB <int> The maximum amount of memory allocated to the VM.

PropertyUpdateWindowEnd <DateTime> Defines the end of the time window wherein if the VM is booted, it will be updated to the latest provisioning scheme and personalization settings.

PropertyUpdateWindowStart <DateTime> Defines the start of the time window wherein if the VM is booted, it will be updated to the latest provisioning scheme and personalization settings.

ProvisioningSchemeName <string> The name of the provisioning scheme associated with the VM.

ProvisioningSchemeUid <Guid> The unique identifier of the provisioning scheme associated with the VM.

ProvisioningSchemeVersion <int> The version of the provisioning scheme currently used by this VM.

ProvVMConfigurationVersion <int> The version of the custom configuration currently used by this VM.

Tag <string> Provides the string associated with a locked VM.

VMId <string> The identifier for the VM in the hypervisor.

VMName <string> The name of the VM in the hypervisor.

AssignedImage <string> The identifier (in the hypervisor) for the hard disk image that the VM is currently assigned.

BootedImage <string> The identifier (in the hypervisor) for the hard disk image with which the VM is currently started.

HostingUnitUid <Guid> The unique identifier of the hosting unit that was used to create the VM.

HypervisorConnectionUid <Guid> The unique identifier of the hypervisor connection that was used to create the VM.

IdentityDiskIndex <int> The disk index on which the identity disk is attached.

LastBootTime <DateTime> The date and time of the last start of the VM.

OSDiskIndex <int> The disk index on which the hard disk image, from which the VM is currently started, is attached. It is set to [int]::MinValue for VMs inherited from versions of XenDesktop 5.6 or earlier.

PersonalVDiskIndex <int> The disk index on which the personal vdisk is attached. Defaults to [int]::MinValue for VMs without a personal vDisk.

PersonalVDiskStorage <string> The identifier (in the hypervisor) for the storage on which the personal vDisk image attached to the VM is located. This is set only if the VM has a personal vDisk attached.

StorageId <string> The identifier (in the hypervisor) for the storage on which the hard disk image, from which the VM is currently started, is located.

NetworkMaps <Citrix.MachineCreation.Sdk.NetworkMap[]> The NIC/network mappings Used to create the VM.

IdentityDiskId <string> The identifier (in the hypervisor) for the identity disk attached to the VM.

IdentityDiskStorage <string> The identifier (in the hypervisor) for the storage on which the identity disk image from which the VM is currently started is located.

PersonalVDiskId <string> The identifier (in the hypervisor) for the personal vDisk attached to the VM. This is set only if the VM has a personal vDisk attached.

SecurityGroups <string[]> The security groups that has been applied to the VM. This only applies in a Cloud provisioning context.

AdditionalStorage <System.Collections.Generic.Dictionary[string, AdditionalStorageDiskImage]> Additional storage disk images attached to this VM keyed by their storage tier names.

UseFullDiskCloneProvisioning <bool> Indicates if the VM was created using the dedicated full disk clone feature.

WriteBackCacheMemorySize <int> The size of the write-back memory cache if specified in MB.

CustomVmData <string> Hypervisor specific custom data packet that has been associated with the virtual machine if any.

WorkgroupMachine <bool> Indicates if the VM is joined to a workgroup.

WindowsActivationType <string> Windows Activation Type of the Provisioned Virtual Machine. The default value is unknown and the field is populated once the virtual machine registers with DDC. This is supported only on 2303 and successive versions.

WindowsActivationStatus <string> Windows Activation Status of the provisioned virtual machine. This is by default set to unknown and is updated when the vda registers with the DDC. The updated values can be Active:The virtual machine is licensed and activated, Inactive:The virtual machine is unlicensed, Errored:An error occured while trying to activate the system.

WindowsActivationStatusErrorCode <string> The default value is Unknown. If successful, it displays as Success, else it displays with the associated error code.

WindowsActivationStatusVirtualMachineError <string> Provides a detailed information of potential error message seen while activating the windows system

Notes

The scope of Import-ProvVm is limited to importing (newly added) VMs only. It assumes

the items below.

  1. Import-AcctIdentityPool is done.
  2. Import-ProvScheme is done.
  3. The input data to Import-ProvVM includes the list of Provisioning VMs.
Import-ProvVM