vRA Developer: Part 4 – Working with vCAC Virtual Machine Entities

In the first post in this series, vRA Developer: Part 1 – IaaS & Understanding The Entity Framework I detailed how you can view the vCAC entities and their associated properties. In this post I am going to cover how you can find a virtual machine entity using different property references and get/update their properties in your vRO workflows. I had intended to provide a single post for this, but felt it would be useful to provide a number of posts, for each specific vCAC entity type. In this post I am going to be looking at the vCAC virtual machine entities.

All code that I have provided or talked about in this post can be downloaded as a vRO package for your consumption here.

Finding vCAC Virtual Machine Entities

When I need to find a vCAC virtual machine entity, there are 4 search references that work well for all of my use cases. These are to search by:

• VirtualMachineID – The entity ID.
• VirtualMachineName – The VM name. Take caution as it’s possible to have duplicate entities with the same VirtualMachineName.
• VMUniqueID – The unique identifier for the vm (i.e. vCenter VM instance UUID).
• ExternalReferenceId – The external reference id (i.e. vCenter VM Id (MoRef)).

I have provided all the Actions below which perform these searches and an example log output for each.

Find Virtual Machine By Entity Id

The following code can be used to get the virtual machine entity by its entity id.

/*global vcacHost virtualMachineId*/

/**
 * Searches for a vcac virtual machine entity by its entity id.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function findVirtualMachineEntityByVirtualMachineId
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} virtualMachineId - The virtual machine entity id.
 * @returns {vCAC:Entity} Returns the virtual machine entity.
 */

function checkParams(vcacHost, virtualMachineId) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!virtualMachineId || typeof virtualMachineId !== "string") {
        inputErrors.push(" - virtualMachineId missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "findVirtualMachineEntityByVirtualMachineId"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var properties = new Properties();
var vcacVmEntity;
var vcacEntityFieldName = "VirtualMachineID";
var entitySetName = "VirtualMachines";
var vcacVmName = "";

try {
    checkParams(vcacHost, virtualMachineId);
    log.log("finding virtual machine entity with entity id: " + virtualMachineId);
    properties.put(vcacEntityFieldName, virtualMachineId);
    vcacVmEntity = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiyByUniqieId(vcacHost,
                                                                                                     entitySetName,
                                                                                                     properties);
    vcacVmName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Found virtual machine entity: " + vcacVmName + " with entity id: " + virtualMachineId);
} catch (e) {
    log.error("Action failed to locate vCAC virtual machine entity.",e);
}

return vcacVmEntity;

Log output:

[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] finding virtual machine entity with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a
[] [I] [Action: findVirtualMachineEntityByVirtualMachineId] Found virtual machine entity: SG-BG-Deliv0005 with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

Find Virtual Machine By Name

The following code can be used to get the virtual machine entity by its name.

/*global vcacHost virtualMachineName*/

/**
 * Searches for a vcac virtual machine entity by VirtualMachineName.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function findVirtualMachineEntityByVirtualMachineName
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} virtualMachineName - The virtual machine name.
 * @returns {vCAC:Entity} Returns the virtual machine entity.
 */

function checkParams(vcacHost, virtualMachineName) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!virtualMachineName || typeof virtualMachineName !== "string") {
        inputErrors.push(" - virtualMachineName missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "findVirtualMachineEntityByVirtualMachineName"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var vmEntity;
var vmEntities = [];
var entitySetName = "VirtualMachines";
var query = "";
var numVmEntities = 0;
var vcacVmEntityId = "";

try {
    checkParams(vcacHost, virtualMachineName);
    log.log("Finding virtual machine entity with vm name: " + virtualMachineName);
    query = "VirtualMachineName eq '" + virtualMachineName + "'";
    vmEntities = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiesBySystemQuery(vcacHost,
                                                                                                       entitySetName,
                                                                                                       query);
    numVmEntities = vmEntities.length;
    if (numVmEntities > 1 ) {
        log.error("More than one virtual machine entity was found with the name: " + virtualMachineName);
    } else if (numVmEntities > 0) {
        vmEntity = vmEntities[0];
        vcacVmEntityId = vmEntity.getProperty("VirtualMachineID");
        log.log("Found virtual machine entity '" + virtualMachineName + "' with entity id: " + vcacVmEntityId);
    } else {
        log.error("No virtual machine entity was found with the name: " + virtualMachineName);
    }
} catch (e) {
    log.error("Action failed to find virtual machine entity by VirtualMachineName",e);
}

return vmEntity;

Log output:

[] [I] [Action: findVirtualMachineEntityByVirtualMachineName] Finding virtual machine entity with vm name: SG-BG-Deliv0005
[] [I] [Action: findVirtualMachineEntityByVirtualMachineName] Found virtual machine entity 'SG-BG-Deliv0005' with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

Find Virtual Machine By Instance UUID

The following code can be used to get the virtual machine entity by its instance uuid.

/*global vcacHost vmUniqueId*/

/**
 * Searches for a vcac virtual machine entity by VmUniqueId.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function findVirtualMachineEntityByVmUniqueId
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} vmUniqueId - The virtual machine unique id.
 * @returns {vCAC:Entity} Returns the virtual machine entity.
 */

function checkParams(vcacHost, vmUniqueId) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!vmUniqueId || typeof vmUniqueId !== "string") {
        inputErrors.push(" - vmUniqueId missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "findVirtualMachineEntityByVmUniqueId"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var vmEntity;
var vmEntities = [];
var entitySetName = "VirtualMachines";
var query = "";
var numVmEntities = 0;
var virtualMachineName = "";
var vcacVmEntityId = "";

try {
    checkParams(vcacHost, vmUniqueId);
    log.log("Finding virtual machine entity with unique id: " + vmUniqueId);
    query = "VMUniqueID eq '" + vmUniqueId + "'";
    vmEntities = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiesBySystemQuery(vcacHost,
                                                                                                       entitySetName,
                                                                                                       query);
    numVmEntities = vmEntities.length;
    if (numVmEntities > 1 ) {
        log.error("More than one virtual machine entity was found with unique id: " + vmUniqueId);
    } else if (numVmEntities > 0) {
        vmEntity = vmEntities[0];
        virtualMachineName = vmEntity.getProperty("VirtualMachineName");
        vcacVmEntityId = vmEntity.getProperty("VirtualMachineID");
        log.log("Found virtual machine entity '" + virtualMachineName + "' with entity id: " + vcacVmEntityId);
    } else {
        log.error("No virtual machine entity was found with unique id: " + vmUniqueId);
    }
} catch (e) {
    log.error("Action failed to find virtual machine entity by VmUniqueId",e);
}

return vmEntity;

Log output:

[] [I] [Action: findVirtualMachineEntityByVmUniqueId] Finding virtual machine entity with unique id: 501a50a4-a968-b447-0058-e27557b0366a
[] [I] [Action: findVirtualMachineEntityByVmUniqueId] Found virtual machine entity 'SG-BG-Deliv0005' with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

Find Virtual Machine By Managed Object Reference (MoRef)

The following code can be used to get the virtual machine entity by its managed object reference.

/*global vcacHost externalReferenceId*/

/**
 * Searches for a vcac virtual machine entity by ExternalReferenceId.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function findVirtualMachineEntityByExternalReferenceId
 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 * @param {string} externalReferenceId - The virtual machine external reference id.
 * @returns {vCAC:Entity} Returns the virtual machine entity.
 */

function checkParams(vcacHost, externalReferenceId) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    if (!externalReferenceId || typeof externalReferenceId !== "string") {
        inputErrors.push(" - externalReferenceId missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "findVirtualMachineEntityByExternalReferenceId"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var vmEntity;
var vmEntities = [];
var entitySetName = "VirtualMachines";
var query = "";
var numVmEntities = 0;
var virtualMachineName = "";
var vcacVmEntityId = "";

try {
    checkParams(vcacHost, externalReferenceId);
    log.log("Finding virtual machine entity with external reference id: " + externalReferenceId);
    query = "ExternalReferenceId eq '" + externalReferenceId + "'";
    vmEntities = System.getModule("com.simplygeek.library.vcac.entities").getVcacEntitiesBySystemQuery(vcacHost,
                                                                                                       entitySetName,
                                                                                                       query);
    numVmEntities = vmEntities.length;
    if (numVmEntities > 1 ) {
        log.error("More than one virtual machine entity was found with unique id: " + externalReferenceId);
    } else if (numVmEntities > 0) {
        vmEntity = vmEntities[0];
        virtualMachineName = vmEntity.getProperty("VirtualMachineName");
        vcacVmEntityId = vmEntity.getProperty("VirtualMachineID");
        log.log("Found virtual machine entity '" + virtualMachineName + "' with entity id: " + vcacVmEntityId);
    } else {
        log.error("No virtual machine entity was found with unique id: " + externalReferenceId);
    }
} catch (e) {
    log.error("Action failed to find virtual machine entity by ExternalReferenceId",e);
}

return vmEntity;

Log output:

[] [I] [Action: findVirtualMachineEntityByExternalReferenceId] Finding virtual machine entity with external reference id: vm-728
[] [I] [Action: findVirtualMachineEntityByExternalReferenceId] Found virtual machine entity 'SG-BG-Deliv0005' with entity id: 05b6a7b4-1cd6-4762-85ce-fe427c33496a

Get Virtual Machine Property Values

The virtual machine entity object has a method ‘.getProperty(“key_string”)‘ that can be used to retrieve a value for a specified property key. When I need to retrieve a value for a property on a virtual machine, I use a helper Action that calls this method and does the main part of the work. I then wrap other Actions around this for the specific property that I need the value for. This can seem a little repetitive but with all the Actions in place, I simply drop them onto my workflows without any thought.

I have created Actions that can retrieve the value for the following virtual machine properties where the correct data type is returned (note this is not the complete set of properties available but the only ones you are ever going to need).

There are of course too many properties here to provide code for. Each Action pretty much looks the same and I’ll provide a couple of examples below. The package link at the beginning of this post will provide Actions for all the above properties.

The following code is the main helper action that retrieves the property value.

/*global vcacEntity, propertyKey*/

/**
 * Retrieves the property value from the provided vCAC Entity and property key.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getPropertyValueFromVcacEntity
 * @param {vCAC:Entity} vcacEntity - The vCAC Entity to get the property value from.
 * @param {string} propertyKey - The property key.
 * @returns {Any} returns the property value.
 */

function checkParams(vcacEntity, propertyKey) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacEntity || System.getObjectType(vcacEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacEntity missing or not of type 'vCAC:Entity'");
    }
    if (!propertyKey || typeof propertyKey !== "string") {
        inputErrors.push(" - propertyKey missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "getPropertyValueFromVcacEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyValue;

try {
    checkParams(vcacEntity, propertyKey);
    log.debug("Getting property value from vcac entity using key: " + propertyKey);
    propertyValue = vcacEntity.getProperty(propertyKey);
    if (!propertyValue) {
        if (propertyValue !== false) {
            log.error("No property value found for '" + propertyKey + "' on vcac entity.");
        }
    }
    log.debug("Found value: " + propertyValue);
} catch (e) {
    log.error("Action failed to get property value from vcac entity.",e);
}

return propertyValue;

This is an example of one of the Actions which act as a wrapper for the above, that is used to get the number of vCPUs assigned to the virtual machine. I have also provided some log output of this being used in a workflow.

/*global vcacVmEntity*/

/**
 * Retrieves the value of the 'VMCPUs' property for the provided vCAC virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getVMCPUsForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {number} Returns the value for the VMCPUs property.
 */

function checkParams(vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}
var logType = "Action";
var logName = "getVMCPUsForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyKey = "VMCPUs";
var propertyValue;

try {
    checkParams(vcacVmEntity);
    log.log("Retrieving property '" + propertyKey + "' from vm entity.");
    propertyValue = System.getModule("com.simplygeek.library.vcac.entities").getPropertyValueFromVcacEntity(vcacVmEntity, propertyKey);
    log.log("Found " + propertyKey + ": " + propertyValue);
} catch (e) {
    log.error("Action failed to get property from vm entity.",e);
}

return propertyValue;

Log output:

[] [I] [Action: getVMCPUsForVirtualMachineEntity] Retrieving property 'VMCPUs' from vm entity.
[] [D] [Action: getPropertyValueFromVcacEntity] Getting property value from vcac entity using key: VMCPUs
[] [D] [Action: getPropertyValueFromVcacEntity] Found value: 1
[] [I] [Action: getVMCPUsForVirtualMachineEntity] Found VMCPUs: 1

Update Virtual Machine Property Values

I have a helper Action that can be used to update a property value on a virtual machine entity. This can be useful if you want to assign the virtual machine to a new blueprint or change the reference for the virtual machine on the parent platform.

Most of the properties can’t or don’t make sense to be updated (as they would get reset during a data collection). The following are valid properties that can be updated and I have provided Actions for.

• BlueprintName
• ComponentName
• ExternalReferenceId
• isManaged
• Notes
• OwnerExists
• VMUniqueID

I also like to take an idempotent approach when performing update operations. Therefore, this helper Action will first check if the current value is the same as the value to be set. If the values are the same, then no update operation is carried out.

/*global System vcacEntity Properties propertyKey propertyValue*/

/**
 * Updates a value of a property on a vcac entity using the value provided.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updatePropertyValueForVcacEntity
 * @param {vCAC:Entity} vcacEntity - The vCAC Entity.
 * @param {string} propertyKey - The property key.
 * @param {string} propertyKey - The property value.
 */

function checkParams(vcacEntity, propertyKey, propertyValue) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacEntity || System.getObjectType(vcacEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacEntity missing or not of type 'vCAC:Entity'");
    }
    if (!propertyKey || typeof propertyKey !== "string") {
        inputErrors.push(" - propertyKey missing or not of type 'string'");
    }
    if (!propertyValue || typeof propertyValue !== "string") {
        inputErrors.push(" - propertyValue missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updatePropertyValueForVcacEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var entityProperties = new Properties();
var entityLink = new Properties();
var updatedEntity;
var currentPropertyValue = "";
var updatedPropertyValue = "";
var vcacEntityName = "";

try {
    checkParams(vcacEntity, propertyKey, propertyValue);
    vcacEntityName = vcacEntity.getInventoryObject().displayName;
    log.log("Attempting to update '" + propertyKey + "' on vcac entity '" + vcacEntityName + "' to '" + propertyValue + "'");
    currentPropertyValue = vcacEntity.getProperty(propertyKey);
    if (currentPropertyValue === propertyValue) {
        log.log("Property '" + propertyKey + "' already set to '" + propertyValue + "', no update required.");
    } else {
        log.log("Updating '" + propertyKey + "' on vcac entity: " + vcacEntityName);
        entityProperties.put(propertyKey, propertyValue);
        updatedEntity = System.getModule("com.simplygeek.library.vcac.entities").updatevCACEntity(vcacEntity, entityProperties, entityLink);
        updatedPropertyValue = updatedEntity.getProperty(propertyKey);
        if (updatedPropertyValue === propertyValue) {
            log.log("Successfully updated '" + propertyKey + "' on vcac entity '" + vcacEntityName + "' to '" + updatedPropertyValue + "'");
        } else {
            log.error("Failed to update '" + propertyKey + "' on vcac entity '" + vcacEntityName + "'");
        }
    }
} catch (e) {
    log.error("Action failed to update property on vcac entity.",e);
}

This is an example of one of the Actions which acts as a wrapper for the above, that is used to change the blueprint that the virtual machine is assigned to. I have also provided some log output of this being used in a workflow.

Update Blueprint Name

The following code can be used to update the blueprint that the virtual machine is assigned to.

/*global vcacVmEntity blueprintName*/

/**
 * Updates the Blueprint that the virtual machine is assigned to.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updateBlueprintNameForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC Virtual Machine Entity.
 * @param {string} blueprintName - The Blueprint Name.
 */

function checkParams(vcacVmEntity, blueprintName) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (!blueprintName || typeof blueprintName !== "string") {
        inputErrors.push(" - blueprintName missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updateBlueprintNameForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyToUpdate = "BlueprintName";

try {
    checkParams(vcacVmEntity, blueprintName);
    System.getModule("com.simplygeek.library.vcac.entities").updatePropertyValueForVcacEntity(vcacVmEntity,
                                                                                              propertyToUpdate,
                                                                                              blueprintName);
} catch (e) {
    log.error("Action failed to update '" + propertyToUpdate + "' on vcac vm entity.",e);
}

Log output when the value being set is different to the current value:

[2019-02-13 16:55:48.717] [I] [Action: updatePropertyValueForVcacEntity] Attempting to update 'BlueprintName' on vcac entity 'SG-BG-Deliv0005' to 'blueprint1'
[2019-02-13 16:55:48.720] [I] [Action: updatePropertyValueForVcacEntity] Updating 'BlueprintName' on vcac entity: SG-BG-Deliv0005
[2019-02-13 16:55:49.084] [I] [Action: updatePropertyValueForVcacEntity] Successfully updated 'BlueprintName' on vcac entity 'SG-BG-Deliv0005' to 'blueprint1'

Log output when the value being set is the same as the current value:

[2019-02-13 16:57:58.802] [I] [Action: updatePropertyValueForVcacEntity] Attempting to update 'BlueprintName' on vcac entity 'SG-BG-Deliv0005' to 'blueprint1'
[2019-02-13 16:57:58.804] [I] [Action: updatePropertyValueForVcacEntity] Property 'BlueprintName' already set to 'blueprint1', no update required.

Update Component Name

The following code can be used to update the component name that the virtual machine is assigned to inside the blueprint.

/*global vcacVmEntity componentName*/

/**
 * Updates the Component Name within the Blueprint that the virtual machine is assigned to.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updateComponentNameForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC Virtual Machine Entity.
 * @param {string} componentName - The Component Name.
 */

function checkParams(vcacVmEntity, componentName) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (!componentName || typeof componentName !== "string") {
        inputErrors.push(" - componentName missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updateComponentNameForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyToUpdate = "ComponentName";

try {
    checkParams(vcacVmEntity, componentName);
    System.getModule("com.simplygeek.library.vcac.entities").updatePropertyValueForVcacEntity(vcacVmEntity,
                                                                                              propertyToUpdate,
                                                                                              componentName);
} catch (e) {
    log.error("Action failed to update '" + propertyToUpdate + "' on vcac vm entity.",e);
}

Update Virtual Machine Description

The following code can be used to update the virtual machine description (this will in turn update the object, for example, in vCenter).

/*global vcacVmEntity description*/

/**
 * Updates the virtual machine description.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updateNotesForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC Virtual Machine Entity.
 * @param {string} description - The virtual machine description.
 */

function checkParams(vcacVmEntity, description) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (!description || typeof description !== "string") {
        inputErrors.push(" - description missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updateNotesForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyToUpdate = "Notes";

try {
    checkParams(vcacVmEntity, description);
    System.getModule("com.simplygeek.library.vcac.entities").updatePropertyValueForVcacEntity(vcacVmEntity,
                                                                                              propertyToUpdate,
                                                                                              description);
} catch (e) {
    log.error("Action failed to update '" + propertyToUpdate + "' on vcac vm entity.",e);
}

Update Virtual Machine Instance UUID

The Following code can be used to update the virtual machine instance uuid. This is useful if the virtual machine has changed locations or has been restored with a new instance uuid (note that the ‘VirtualMachine.Admin.UUID’ custom property would also need to be updated that is detailed in a followup post).

/*global vcacVmEntity VMUniqueID*/

/**
 * Updates the vm unique id of the virtual machine object on the parent platform.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updateVMUniqueIDForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC Virtual Machine Entity.
 * @param {string} VMUniqueID - The VMUniqueID (i.e. vCenter VM UUID).
 */

function checkParams(vcacVmEntity, VMUniqueID) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (!VMUniqueID || typeof VMUniqueID !== "string") {
        inputErrors.push(" - VMUniqueID missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updateVMUniqueIDForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyToUpdate = "VMUniqueID";

try {
    checkParams(vcacVmEntity, VMUniqueID);
    System.getModule("com.simplygeek.library.vcac.entities").updatePropertyValueForVcacEntity(vcacVmEntity,
                                                                                              propertyToUpdate,
                                                                                              VMUniqueID);
} catch (e) {
    log.error("Action failed to update '" + propertyToUpdate + "' on vcac vm entity.",e);
}

Update Virtual Machine Managed Object Reference

The following code can be used to update the virtual machine Id (MoRef). This is useful if the virtual machine has changed locations or has been restored with a new id.

/*global vcacVmEntity externalReferenceId*/

/**
 * Updates the external reference id of the virtual machine object on the parent platform.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function updateExternalReferenceIdForVirtualMachineEntity
 * @param {vCAC:Entity} vcacVmEntity - The vCAC Virtual Machine Entity.
 * @param {string} externalReferenceId - The ExternalReferenceId (i.e. MoRef Id).
 */

function checkParams(vcacVmEntity, externalReferenceId) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacVmEntity || System.getObjectType(vcacVmEntity) !== "vCAC:Entity") {
        inputErrors.push(" - vcacVmEntity missing or not of type 'vCAC:Entity'");
    }
    if (!externalReferenceId || typeof externalReferenceId !== "string") {
        inputErrors.push(" - externalReferenceId missing or not of type 'string'");
    }
    if (inputErrors.length > 0) {
        errorMessage = "Mandatory parameters not satisfied:\n" + inputErrors.join("\n");
        log.error(errorMessage);
    }
}

var logType = "Action";
var logName = "updateExternalReferenceIdForVirtualMachineEntity"; // This must be set to the name of the action
var Logger = System.getModule("com.simplygeek.library.util").logger(logType, logName);
var log = new Logger(logType, logName);
var propertyToUpdate = "ExternalReferenceId";

try {
    checkParams(vcacVmEntity, externalReferenceId);
    System.getModule("com.simplygeek.library.vcac.entities").updatePropertyValueForVcacEntity(vcacVmEntity,
                                                                                              propertyToUpdate,
                                                                                              externalReferenceId);
} catch (e) {
    log.error("Action failed to update '" + propertyToUpdate + "' on vcac vm entity.",e);
}

I hope this has been useful. The original post was quite large and in the end I had to break down into 3 separate posts.

If you discover bugs with any of my code, require some help or simply need an ad-hoc solution, then please drop me a message via the Drift app.