vRA Developer: Part 5 – Working with vCAC Virtual Machine Linked Entities

In my previous post vRA Developer: Part 4 – Working with vCAC Virtual Machine Entities, I demonstrated how you could find vCAC virtual machine entities and retrieve and update their properties. In this post I am going to focus on linked entities.

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

There are additional properties that can be retrieved which are part of other entities that the virtual machine has a relationship with. Here are some examples of information that can be retrieved through linked entities (the code for all of these examples is included in the package link provided at the beginning of this post).

• Host/Cluster Name
• Reservation Name
• Owner Username
• IPv4 Addresses
• Snapshots
• Networks

The virtual machine entity object has a method ‘.getLink(vcacHost, “linkKey_string”)‘ that can be used to get the linked entity objects. The ‘.getProperty(“key_string”)‘ can then be used on these entities to get a specific property value, such as the reservation name.

Get the Host or Cluster Name

The following code can be used to get the host or cluster name that the virtual machine (this is referred to as the compute resource within the vRA portal) is hosted on.

/*global vcacHost vcacVmEntity*/

/**
 * Get the compute resource name for the vcac virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getComputeResourceNameForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string} Returns the compute resource name.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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 = "getComputeResourceNameForVirtualMachineEntity"; // 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 hostEntities = [];
var hostEntity;
var hostName = "";
var hostId = "";
var vmEntityName = "";
var numHostEntities = 0;

try {
    checkParams(vcacHost, vcacVmEntity);
    vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Getting compute resource name for virtual machine entity: " + vmEntityName);
    hostEntities = vcacVmEntity.getLink(vcacHost, "Host");
    numHostEntities = hostEntities.length;
    if (numHostEntities > 1 ) {
        log.error("More than one compute resource was found.");
    } else if (numHostEntities > 0) {
        hostEntity = hostEntities[0];
        hostName = hostEntity.getProperty("HostName");
        hostId = hostEntity.getProperty("HostID");
        log.log("Found compute resource '" + hostName + "' with entity id '" + hostId + "'");
    } else {
        log.error("No compute resource was found.");
    }
} catch (e) {
    log.error("Action failed to get compute resource name for virtual machine entity.",e);
}

return hostName;

Log output:

[] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Getting compute resource name for virtual machine entity: SG-BG-Deliv0005
[] [I] [Action: getComputeResourceNameForVirtualMachineEntity] Found compute resource 'SITEA-CLS-CLOUD-01' with entity id '355c617e-f9e0-4726-abcf-81f5748c50db'

Get the Reservation Name

The following code is used to get the reservation name that the virtual machine is provisioned on.

/*global vcacHost vcacVmEntity*/

/**
 * Get the reservation name for the vcac virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getReservationNameForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string} Returns the reservation name.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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 = "getReservationNameForVirtualMachineEntity"; // 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 reservationEntity;
var reservationName = "";
var vmEntityName = "";

try {
    checkParams(vcacHost, vcacVmEntity);
    vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Getting reservation name for virtual machine entity: " + vmEntityName);
    reservationEntity = System.getModule("com.simplygeek.library.vcac.vm.links").getReservationEntityForVirtualMachineEntity(vcacHost,
                                                                                                                             vcacVmEntity);
    reservationName = reservationEntity.getProperty("HostReservationName");
    log.log("Found reservation: " + reservationName);
} catch (e) {
    log.error("Action failed to get reservation name for virtual machine entity.",e);
}

return reservationName;

The above code also uses the below helper ‘getReservationEntityForVirtualMachineEntity’.

/*global vcacHost vcacVmEntity*/

/**
 * Get the reservation entity for the vcac virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getReservationEntityForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {vCAC:Entity} Returns the reservation entity.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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 = "getReservationEntityForVirtualMachineEntity"; // 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 reservationEntities = [];
var reservationEntity;
var reservationName = "";
var reservationId = "";
var vmEntityName = "";
var numResEntities = 0;

try {
    checkParams(vcacHost, vcacVmEntity);
    vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.debug("Getting reservation name for virtual machine entity: " + vmEntityName);
    reservationEntities = vcacVmEntity.getLink(vcacHost, "HostReservation");
    numResEntities = reservationEntities.length;
    if (numResEntities > 1 ) {
        log.error("More than one reservation was found.");
    } else if (numResEntities > 0) {
        reservationEntity = reservationEntities[0];
        reservationName = reservationEntity.getProperty("HostReservationName");
        reservationId = reservationEntity.getProperty("HostReservationID");
        log.debug("Found reservation '" + reservationName + "' with entity id '" + reservationId + "'");
    } else {
        log.error("No reservation was found.");
    }
} catch (e) {
    log.error("Action failed to get reservation name for virtual machine entity.",e);
}

return reservationEntity;

Log output:

[] [I] [Action: getReservationNameForVirtualMachineEntity] Getting reservation name for virtual machine entity: SG-BG-Deliv0005
[] [D] [Action: getReservationEntityForVirtualMachineEntity] Getting reservation name for virtual machine entity: SG-BG-Deliv0005
[] [D] [Action: getReservationEntityForVirtualMachineEntity] Found reservation 'RES-SITEA-vSphere-Resource-01' with entity id '8e1534f6-c65c-412b-af8b-b4ad8ee3c6cb'
[] [I] [Action: getReservationNameForVirtualMachineEntity] Found reservation: RES-SITEA-vSphere-Resource-01

Get the Owner Username

The following code can be used to get the username (UPN) of the user who owns the virtual machine.

/*global vcacHost vcacVmEntity*/

/**
 * Get the owner username for the vcac virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getOwnerForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string} Returns the owner username in UPN format.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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 = "getOwnerForVirtualMachineEntity"; // 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 ownerEntities = [];
var ownerEntity;
var ownerUsername = "";
var vmEntityName = "";
var numOwnerEntities = 0;

try {
    checkParams(vcacHost, vcacVmEntity);
    vmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Getting owner username for virtual machine entity: " + vmEntityName);
    ownerEntities = vcacVmEntity.getLink(vcacHost, "Owner");
    numOwnerEntities = ownerEntities.length;
    if (numOwnerEntities > 1 ) {
        log.error("More than one owner was found.");
    } else if (numOwnerEntities > 0) {
        ownerEntity = ownerEntities[0];
        ownerUsername = ownerEntity.getProperty("UserName");
        log.log("Found owner username: " + ownerUsername);
    } else {
        log.error("No owner was found.");
    }
} catch (e) {
    log.error("Action failed to get owner username for virtual machine entity.",e);
}

return ownerUsername;

Log output:

[] [I] [Action: getOwnerForVirtualMachineEntity] Getting owner username for virtual machine entity: SG-BG-Deliv0005
[] [I] [Action: getOwnerForVirtualMachineEntity] Found owner username: stephensg@sgroot.local

Get a List of IPv4 Addresses assigned to the VM

The following code can be used to get a list of IPv4 addresses that are assigned to the virtual machine.

/*global vcacHost vcacVmEntity*/

/**
 * Retrieves a list of IPv4 addresses assigned to the vCAC virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getStaticIPv4AddressesForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string[]} Returns the list of IPv4 addresses.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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 = "getStaticIPv4AddressesForVirtualMachineEntity"; // 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 linkKey = "StaticIPv4Addresses";
var ipv4AddressEntities = [];
var ipv4Addresses = [];
var numIpv4Addresses = 0;
var vcacVmEntityName = "";

try {
    checkParams(vcacHost, vcacVmEntity);
    vcacVmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Retrieving list of IPv4 Addresses assigned to vcac vm entity: " + vcacVmEntityName);
    ipv4AddressEntities = vcacVmEntity.getLink(vcacHost, linkKey);
    ipv4Addresses = ipv4AddressEntities.map(function(x){return x.getProperty("IPv4Address");});
    numIpv4Addresses = ipv4Addresses.length;
    log.log("Found " + numIpv4Addresses + " IPv4 Addresses.");
} catch (e) {
    log.error("Action failed to get list of IPv4 Addresses",e);
}

return ipv4Addresses;

Get a List of Snapshots Created on the VM

The following code can be used to get the details and list of snapshot names that have been created on the virtual machine.

/*global vcacHost vcacVmEntity*/

/**
 * Retrieves a list of snapshots created on the vCAC virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getVMSnapshotsForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string[]} Returns the list of IPv4 addresses.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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);
    }
}

function getSnapshot(snapshot) {
    var snapshotName = snapshot.getProperty("Name");
    var snapshotDate = snapshot.getProperty("CreatedDatetime");
    log.log("Found snapshot '" + snapshotName + "' created on: " + snapshotDate);
    return snapshotName;
}

var logType = "Action";
var logName = "getVMSnapshotsForVirtualMachineEntity"; // 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 linkKey = "VMSnapshots";
var vmSnapshotEntities = [];
var vmSnapshots = [];
var numVmSnapshots = 0;
var vcacVmEntityName = "";

try {
    checkParams(vcacHost, vcacVmEntity);
    vcacVmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Retrieving list of snapshots created on virtual machine: " + vcacVmEntityName);
    vmSnapshotEntities = vcacVmEntity.getLink(vcacHost, linkKey);
    vmSnapshots = vmSnapshotEntities.map(function(x){return getSnapshot(x);});
    numVmSnapshots = vmSnapshots.length;
    log.log("Found " + numVmSnapshots + " snapshots.");
} catch (e) {
    log.error("Action failed to get list of snapshots",e);
}

return vmSnapshots;

Log output:

[] [I] [Action: getVMSnapshotsForVirtualMachineEntity] Retrieving list of snapshots created on virtual machine: SG-BG-Deliv0005
[] [I] [Action: getVMSnapshotsForVirtualMachineEntity] Found snapshot 'SG-BG-Deliv0005 (15-02-2019 14:32:50)' created on: Fri Feb 15 2019 14:27:42 GMT-0000 (UTC)
[] [I] [Action: getVMSnapshotsForVirtualMachineEntity] Found 1 snapshots.

Get a List of Networks the VM is Attached to

The following code can be used to get a list of networks that are attached to the virtual machines’ network adaptors.

/*global vcacHost vcacVmEntity*/

/**
 * Retrieves a list of networks assigned to the vCAC virtual machine entity.
 * @author Gavin Stephens <gavin.stephens@simplygeek.co.uk>
 * @version 1.1.0
 * @function getVMToNetworksForVirtualMachineEntity
 * @param {vCAC:VCACHOST} vcacHost - The vCAC Host.
 * @param {vCAC:Entity} vcacVmEntity - The vCAC virtual machine entity.
 * @returns {string[]} Returns the list of IPv4 addresses.
 */

function checkParams(vcacHost, vcacVmEntity) {
    var inputErrors = [];
    var errorMessage;
    if (!vcacHost || System.getObjectType(vcacHost) !== "vCAC:VCACHost") {
        inputErrors.push(" - vcacHost missing or not of type 'vCAC:VCACHost'");
    }
    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);
    }
}

function getNetwork(network) {
    var networkName = network.getLink(vcacHost, "HostNic")[0].getProperty("NetworkName");
    log.log("Found network '" + networkName);
    return networkName;
}

var logType = "Action";
var logName = "getVMToNetworksForVirtualMachineEntity"; // 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 linkKey = "VMToNetworks";
var networkEntities = [];
var networks = [];
var numNetworks = 0;
var vcacVmEntityName = "";

try {
    checkParams(vcacHost, vcacVmEntity);
    vcacVmEntityName = vcacVmEntity.getProperty("VirtualMachineName");
    log.log("Retrieving list of networks assigned to vcac vm entity: " + vcacVmEntityName);
    networkEntities = vcacVmEntity.getLink(vcacHost, linkKey);
    networks = networkEntities.map(function(x){return getNetwork(x);});
    numNetworks = networks.length;
    log.log("Found " + numNetworks + " networks.");
} catch (e) {
    log.error("Action failed to get list of networks.",e);
}

return networks;

Log output:

[] [I] [Action: getVMToNetworksForVirtualMachineEntity] Retrieving list of networks assigned to vcac vm entity: SG-BG-Deliv0005
[] [I] [Action: getVMToNetworksForVirtualMachineEntity] Found network 'vxw-dvs-314-virtualwire-8-sid-5005-SiteA-Transit-South
[] [I] [Action: getVMToNetworksForVirtualMachineEntity] Found 1 networks.

I hope this has been useful. If you discover any 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.