Updating custom fields

This is yet another powercli script turned workflow, the powercli version has been in use for the last couple of years.

The idea is to present some information that is not available in vCenter using the custom fields. For example, since the tasks and events are aged out of the vCenter database after a while I capture the data while it is still available and save it to custom fields. Another example is the actual version of the VMware tools, inside the vCenter client you can’t see the version number, you can only see if they are up to date or not.

Ok, so how did I do this?

Workflow

I started with creating a workflow that takes a single VM as the input and updates the properties on that one VM.

Functions

I created a couple of simple functions to make the code cleaner, the first one was the getField function which returns the VcCustomFieldDef of a field if it exists and if it doesnt exist it creates it.

function getField( manager, name )
{
	for each( var field in manager.field )
	{
		if( field.name == name )
		{
			return field;
		}
	}

	return manager.addCustomFieldDef(name, "VirtualMachine", null, null);
}

function getField( manager, name )

{

for each( var field in manager.field )

{

if( field.name == name )

{

return field;

}

return manager.addCustomFieldDef(name, "VirtualMachine", null, null);

}

Not much there, all it does is loop over the fields in the VcCustomFieldsManager.fields collection and returns the one that matches the name you pass in. If the field does not exist it creates a new one with that name and returns the newly created field.

Then we have the getValue function, this one returns the value of a custom property on the VM you pass in.

function getValue( vm, field )
{
	for each( var value in vm.customValue )
	{
		if( value.key == field.key )
		{
			return value.value;
		}
	}

	return null;
}

function getValue( vm, field )

{

for each( var value in vm.customValue )

{

if( value.key == field.key )

{

return value.value;

}

return null;

}

Same thing here, nothing fancy. All it does is loop over the custom fields in the vm and checks to see if the key of it matches the VcCustomFieldDef object that you retrieved using the getField function above.
As a side note, the value property of this object is not in the API documentation inside the vOrchestrator client but it does work.

The last function is a really small one that you use to update the custom properties, in reality there is hardly a need for this to be in a function but I decided to do it anyway to make the code more consistent.

function setValue( vm, field, value )
{
	vm.setCustomValue(field.name, value);
}

function setValue( vm, field, value )

{

vm.setCustomValue(field.name, value);

}

Getting the field definitions

Once you have these functions it is pretty simple to work with custom fields in vOrchestrator. The first thing I do in the workflow is to get the VcCustomFieldDef objects for my fields so that I have them handy.

// Get the custom fields manager
var customFieldsManager = VirtualMachine.sdkConnection.customFieldsManager;

// Get the custom fields
createdOnField = getField(customFieldsManager, createdOnFieldName);
createdByField = getField(customFieldsManager, createdByFieldName);
firstSeenField = getField(customFieldsManager, firstSeenFieldName);
toolsVersionField = getField(customFieldsManager, toolsVersionFieldName);

// Get the custom fields manager

var customFieldsManager = VirtualMachine.sdkConnection.customFieldsManager;

// Get the custom fields

createdOnField = getField(customFieldsManager, createdOnFieldName);

createdByField = getField(customFieldsManager, createdByFieldName);

firstSeenField = getField(customFieldsManager, firstSeenFieldName);

toolsVersionField = getField(customFieldsManager, toolsVersionFieldName);

Reading the current value of the fields

Then I get the current values of the custom fields.

currentCreatedOn = getValue(VirtualMachine, createdOnField);
currentCreatedBy = getValue(VirtualMachine, createdByField);
currentFirstSeen = getValue(VirtualMachine, firstSeenField);
currentToolsVersion = getValue(VirtualMachine, toolsVersionField);

currentCreatedOn = getValue(VirtualMachine, createdOnField);

currentCreatedBy = getValue(VirtualMachine, createdByField);

currentFirstSeen = getValue(VirtualMachine, firstSeenField);

currentToolsVersion = getValue(VirtualMachine, toolsVersionField);

At this point I’m ready to compare the properties of the virtual machine with the custom fields and update them as necessary. I’ll show the VMware tools code first as it is much shorter and I’ll go in to the code necessary to retrieve the events later.

VMware tools version

First I get the tools version from the guest property of the virtual machine, you’ll notice that I check for null’s and if it is null I set the value to “Unknown”.

var toolsVersion = (VirtualMachine.guest.toolsVersion == null ? "Unknown" : VirtualMachine.guest.toolsVersion);

1	var toolsVersion = (VirtualMachine.guest.toolsVersion == null ? "Unknown" : VirtualMachine.guest.toolsVersion);

Since I only get to this code if the version doesn’t match the field (see the workflow above), all I have to do then is to update the custom field with the new version of the tools.

// Set tools version
setValue( VirtualMachine, toolsVersionField, toolsVersion );

1 2	// Set tools version setValue( VirtualMachine, toolsVersionField, toolsVersion );

CreatedBy and CreatedOn

The next thing to do is to save the date that the virtual machine was created and by who. To do this we need to use the EventFilter functionality and search for specific types of events.

First we get the VcEventManger object from the SdkConnection and create the filter that we are going to use to search with.

var eventManager = VirtualMachine.sdkConnection.eventManager;
var eventFilter = new VcEventFilterSpec();

1 2	var eventManager = VirtualMachine.sdkConnection.eventManager; var eventFilter = new VcEventFilterSpec();

Then we add the entity filter to that object, this is what ensures that we only get events for the virtual machine we are interested in.

var entityFilter = new VcEventFilterSpecByEntity();
entityFilter.entity = VirtualMachine;
entityFilter.recursion = VcEventFilterSpecRecursionOption.all;
eventFilter.entity = entityFilter;

var entityFilter = new VcEventFilterSpecByEntity();

entityFilter.entity = VirtualMachine;

entityFilter.recursion = VcEventFilterSpecRecursionOption.all;

eventFilter.entity = entityFilter;

The next step is to add the event type filter to the search criteria.

var types = new Array();
types.push("VmBeingDeployedEvent");
types.push("VmCreatedEvent");
types.push("VmRegisteredEvent");
types.push("VmClonedEvent");
eventFilter.Type = types;

var types = new Array();

types.push("VmBeingDeployedEvent");

types.push("VmCreatedEvent");

types.push("VmRegisteredEvent");

types.push("VmClonedEvent");

eventFilter.Type = types;

At this point we are ready to execute our search, we do that by creating a EventCollector, rewinding it and grabbing the first 20 events.

var collector = eventManager.createCollectorForEvents(eventFilter);
collector.rewindCollector();
var events = collector.readNextEvents(20);

var collector = eventManager.createCollectorForEvents(eventFilter);

collector.rewindCollector();

var events = collector.readNextEvents(20);

Now we are ready to check to see if our search returned any events and if so we grab the timestamp and the username from the event and then we format the timestamp in to a format that we can later use in excel to do more ad-hoc reports.

if( events != null && events.length > 0 )
{
	var createdTime = events[0].createdTime;
	createdBy = events[0].userName;
	createdTimeString = formatDate(createdTime);
}

if( events != null && events.length > 0 )

{

var createdTime = events[0].createdTime;

createdBy = events[0].userName;

createdTimeString = formatDate(createdTime);

}

The last step is to update the custom fields of the virtual machine.

if( currentCreatedOn != createdTimeString )
{
	Server.log( VirtualMachine.name + " - Updating created on (before: " + currentCreatedOn + ", after: " + createdTimeString + ").");
	setValue( VirtualMachine, createdOnField, createdTimeString );
	currentCreatedOn = createdTimeString;
}

if( currentCreatedOn != createdTimeString )

{

Server.log( VirtualMachine.name + " - Updating created on (before: " + currentCreatedOn + ", after: " + createdTimeString + ").");

setValue( VirtualMachine, createdOnField, createdTimeString );

currentCreatedOn = createdTimeString;

}

To release resources we destroy the event collector before we continue the workflow.

collector.destroyCollector();

1	collector.destroyCollector();

First Seen

The code that updates the FirstSeen field is pretty much the same as the code that updates the CreatedBy and CreatedOn fields except that it does not filter the events by type. And if for some reason you get no events at all back from the search it sets it to the current time.

Conclusion (TL;DR)

The very last step is to create a workflow that loops over all your different vCenter servers and all the virtual machines in them and runs this workflow on them.

You can either do this with a single workflow or you can create each step in the process individually and use the foreach workflow loops to do the logic, like this:

The CreatedOn and CreatedBy (aka. Blame) fields can be very handy when you are trying to figure out who deployed a specific virtual machine and when. Unfortunately since vCenter ages out events you will end up with quite a few virtual machines with unknown createtion dates/usernames, that is why I also added the FirstSeen column, it has the first time that the script saw the virtual machine in vCenter.

Orchestrate This!

I would much rather spend an hour scripting a task than an hour doing the work by hand.