Aegis ‘Depot’ Activity – Hyper-V Integration Part 1 - Finding, Viewing and Changing Virtual Machine State

Aegis ‘Depot’ Activity – Hyper-V Integration Part 1 - Finding, Viewing and Changing Virtual Machine State

Welcome to Part 1 of Hyper-V Integration Activities for NetIQ Aegis.   This is a 4 part cool tool Activity Library which will introduce and extend the functionality with new activities in each part bringing the power of Aegis Automation to Hyper-V environments.

Managing Hyper-V via Powershell is a pretty common scenario in different levels of automation and is certainly an option also in Aegis via the 'Run Script' activities.  While I am a big fan of using scripts in workflows where it makes sense to, for the novice workflow developer parsing script outputs and working out inputs however simple can be a challenge especially when they didn't write the script!  I find long term dedicated Activities are always preferable as it makes dealing with Hyper-V the same as dealing with everything else.

So first things first - In Hyper-V you can use duplicate names for your virtual machines - this may not be done in practice but it does mean that we can't identify individual Virtual Machines by its displayname ('ElememenName') as it is not reliable where duplicates exist and you may end up powering off the wrong VM - or worse!   Each VM has its own unique identifier which we will use when performing operations on Virtual Machines.  How we find this value to begin with?  Check out the first Hyper-V activity - Find VMs.


Find VMs

The Find VMs activity does as you'd expect, it find VMs on a Hyper-V Server.  It allows two different types of searches, by Display Name or by WMI filter.  The Activities in the background use WMI so if you are familiar with the Hyper-V WMI Classes you may want to give this option a try.  Usually though you may know the VM Display Name and want to find its unique identifier.


The Connection input section is common across all Hyper-V activities and defines where and how to connect to Hyper-V.

The Config section for the Find VMS activity is basically a choice between searching by WMI filter or by VM Display Name.


At runtime, the example below show a result where I have two VMs with the same name (ElementName).  A bit of workflow logic can be used with the 'Result Count' output (not visible) in order to handle duplicate results.


Where a single result is found then you can use the first result in the 'Result Array' output as the Instance ID of the Virtual machine in other activities as this will be the correct value for the VM.


If you have more than one result you can pass the results via the 'Get VM Details' activity to return more data on the Virtual Machine to determine which is the correct VM you are looking for.


Get VM Details

This activity returns a range of outputs of details relating to a particular Virtual Machine.  Apart from the connection information it only requires the Instance ID of a VM as found by the 'Find VMs' activity to run.



Now that we can find VMs and identify their systems details in case we have duplicates we can start performing actions on the VMs!


Change VM Power State

The 'Change VM Power State' activity is the last activity in Part 1.  It can be used to Power On/Off and Pause a VM.  With all of the Hyper-V activities it will be important that the VM machine is in the correct state before performing an operation - for example if a VM is shutting down you won't be able to start it up again - use a pause activity and use the 'Get VM Details' activity to check the current status via 'EnabledState' before attempting the next operation.  If you use this activity to change the state power it 'ON' for example the activity will complete but the VM may be still in a 'Starting' state for some time.


The activity configuration is pretty simple - inputs as before and then just select the new State from the drop-down - ON (Enabled) OFF (Disabled) or PAUSE.

The activity outputs are a simple True/False for success result and an additional error message output for when the operation failed normally due to the VM being in the wrong state.


So there you go - watch out for Part 2 where I'll be adding on activities to work with automating VM Snapshots!


Activity Installation Instructions are here:


Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Top Contributors
Version history
Revision #:
1 of 1
Last update:
‎2015-02-05 20:56
Updated by:
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.