vROps Reports and PowerCLI Part 3: A Helper Module
For your reference here is a list of the articles in this mini-series.
- vROps Reports and PowerCLI Part 1: Generating Reports
- vROps Reports and PowerCLI Part 2: Downloading Reports
- vROps Reports and PowerCLI Part 3: A Helper Module (this article)
Introduction
If you have been following along with the previous two articles in this series, you should now have a pretty good understanding of how to manipulate the extensionData container via PowerCLI to generate and download reports from vRealize Operations Manager (vROps). However, I’m sure you’ll agree that using the extensionData container and its methods directly can be pretty cumbersome. That is why I have put together a helper module which provides a couple of functions to help simplify things a bit.
Using The Module
Installation
This module is hosted on my public GitHub. Therefore, to install it you first need to clone the repository.
git clone https://github.com/ryan-jan/vROps-Reports.git
Then import the module into your PowerShell session.
Import-Module .\vROps-Reports\vROps-Reports.psd1
Generating A Report
The first thing we need to do is find the ReportDefinition (that’s a Report Template if you are looking in the Web UI) that we want to generate and assign it to a variable. For this we use the Get-OMReportDefinition function. If you run this function with no arguments it will return a list of all available definitions. However, I am looking for the Oversized VMs Report in particular so I use the Name parameter to filter the results.
Get-OMReportDefinition -Name 'Oversized VMs'
Name : Oversized VMs Report
Description : Oversized VMs Report
Subject : {Virtual Machine}
Traversalspecs : {vSphere Networking, Custom Datacenters, vSphere Hosts and Clusters, vSphere Storage}
LastRunTime : 01/01/0001 00:00:00
LastRunTimeSpecified : False
Owner : admin
Links :
Any :
Id : 1f69952f-7ff4-4d2c-9446-81a811de19b0
CreationTime : 01/01/0001 00:00:00
Active : True
ActiveSpecified : True
AnyAttr :
Once I have the Id for the ReportDefinition I can assign it to a variable for later use.
$ReportDefinition = Get-OMReportDefinition -Id 1f69952f-7ff4-4d2c-9446-81a811de19b0
Next, we need to assign the TraversalSpec we are targeting to a variable in the same way. We will use the Get-OMTraversalSpec function to achieve this. If you run Get-OMTraversalSpec with no parameters it will return a list of all available TraversalSpec objects. However, if you take a look at the $ReportDefinition variable we just created, you can see which TraversalSpecs the ReportDefinition you are generating will accept.
$ReportDefinition.Traversalspecs
Name : vSphere Networking
Description : View the vSphere distributed switches
RootAdapterKindKey : VMWARE
RootResourceKindKey : vSphere World
Any :
AdapterInstanceAssociation : False
AnyAttr :
Name : Custom Datacenters
Description : Navigation for Custom Datacenters
RootAdapterKindKey : VMWARE
RootResourceKindKey : CustomDatacenter
Any :
AdapterInstanceAssociation : False
AnyAttr :
Name : vSphere Hosts and Clusters
Description : Enables view of resources imported from vCenter like Clusters, Hosts, VMs and ResourcePools
RootAdapterKindKey : VMWARE
RootResourceKindKey : vSphere World
Any :
AdapterInstanceAssociation : False
AnyAttr :
Name : vSphere Storage
Description : Enables view of storage resources imported from vCenter like Datastores and Datastore
Clusters
RootAdapterKindKey : VMWARE
RootResourceKindKey : vSphere World
Any :
AdapterInstanceAssociation : False
AnyAttr :
I can see that the Oversized VMs Report will only accept four TraversalSpec objects; vSphere Networking, Custom Datacenters, vSphere Hosts and Clusters, and vSphere Storage. I am going to use vSphere Hosts and Clusters in this example. I can find more information about this TraversalSpec using the Get-OMTraversalSpec function with the Name parameter.
Get-OMTraversalSpec -Name "vSphere Hosts and Clusters"
Name : vSphere Hosts and Clusters
Description : Enables view of resources imported from vCenter like Clusters, Hosts, VMs and ResourcePools
RootAdapterKindKey : VMWARE
RootResourceKindKey : vSphere World
Any :
AdapterInstanceAssociation : False
AnyAttr :
I will assign it to a variable in the same way that we did for the ReportDefinition
$TraversalSpec = Get-OMTraversalSpec -Name "vSphere Hosts and Clusters"
Finally, we need to assign the resource that we are targeting to a variable. There is already a Get-OMResource cmdlet in the VMware.VimAutomation.vROps PowerCLI module, so we will use this. You can find more information about this cmdlet here. I am going to target my whole vCenter instance, but you can target any resource you like e.g. Datacenter, Cluster VM etc.
Get-OMResource -Name 'vcenter.example.com' | Format-List
Name : vcenter.example.com
ExtensionData : VMware.VimAutomation.VROps.Views.ResourceDto
Health : Green
HealthValue : 100
SolutionObjectId :
DynamicTresholdEnabled : True
AdapterInstanceId : bf9df5f2-7cae-46bc-bee8-42057e43bf02
Status : DataReceiving
State : Started
StatusMessage :
Location : Unknown
AdapterKind : VMWARE
ResourceKind : VMwareAdapter Instance
Created : 26/10/2015 10:03:58
Description :
IsOrphaned : False
Id : bf9df5f2-7cae-46bc-bee8-42057e43bf02
$Resource = Get-OMResource -Name 'vcenter.example.com'
Now that we have these three objects, we can use the New-OMReport function to generate the report in vROps.
New-OMReport -Resource $Resource -ReportDefinition $ReportDefinition -TraversalSpec $TraversalSpec
Name :
Description : Oversized VMs Report
ResourceId : bf9df5f2-7cae-46bc-bee8-42057e43bf02
ReportDefinitionId : 1f69952f-7ff4-4d2c-9446-81a811de19b0
TraversalSpec :
Subject : VirtualMachine
Owner : 786b4832-00f9-46c6-b35e-56bead7d9b87
CompletionTime : null
Status : QUEUED
Links : {linkToSelf, linkToResource, linkToReportDefinition}
Any :
Id : bbe046cf-b2a3-4860-b7e8-f2b85f177520
AnyAttr :
The report is now being generated and as you can see its current status is QUEUED. By specifying its Id, we can use the Get-OMReport function to check the status of this report.
Get-OMReport -Id bbe046cf-b2a3-4860-b7e8-f2b85f177520
Name :
Description : Oversized VMs Report
ResourceId : bf9df5f2-7cae-46bc-bee8-42057e43bf02
ReportDefinitionId : 1f69952f-7ff4-4d2c-9446-81a811de19b0
TraversalSpec :
Subject : VirtualMachine
Owner : 786b4832-00f9-46c6-b35e-56bead7d9b87
CompletionTime : Sun Jun 10 11:12:34 BST 2018
Status : COMPLETED
Links : {linkToSelf, linkToResource, linkToReportDefinition}
Any :
Id : bbe046cf-b2a3-4860-b7e8-f2b85f177520AnyAttr :
That’s it! Once the status has changed to COMPLETED the report has been generated and is ready to be received.
Recieving A Generated Report
Now we have generated a report, we need to retrieve it from the vROps server. This is where the Recieve-OMReport function comes in to play. Using this function we are able to either download the report as a CSV or PDF file, or retrieve the data into a PowerShell object to manipulate the data further. I’m not going to go into great detail on this as it really is quite straight forward.
Here’s how you receive the report as a PowerShell object.
$Report = Get-OMReport -Id bbe046cf-b2a3-4860-b7e8-f2b85f177520
Receive-OMReport -Report $Report
Downloading to CSV and PDF files is just as easy.
$Report = Get-OMReport -Id bbe046cf-b2a3-4860-b7e8-f2b85f177520
Receive-OMReport -Report $Report -CSV -Path "C:\Report.csv"
# Or as a PDF
Receive-OMReport -Report $Report -PDF -Path "C:\Report.csv"
Conclusion
I hope you have found these articles helpful in understanding how to fully utilise the vROps API from a PowerCLI session. I use this module frequently and it really does save time when working with the report data from vROps. If you have any suggestions on how this module could be improved or additional functionality that you would like to see, please get in touch via Twitter or GitHub.
