Exporting and Importing vRO Workflows with PowervRO

There are a number of different ways to get your developed vRO content from one system to another: exporting / importing single items, exporting / importing vRO Packages containing multiple items, synchronising content directly between vRO systems.

In this example I’ll show you how to use PowervRO to export and import workflows from and to vRO.

Export vRO Workflows

To export a single workflow is pretty straightforward with the function Export-vROWorkflow:

However, without much extra effort we can leverage some standard PowerShell functionality and export a whole folder (category) of vRO workflows:

PowervRO14

PowervRO15

PowervRO16

 

Import vRO Workflows

Say we are now working on a new vRO system with the same folder structure, we can import one of the exported workflows with the following (note we need to find the ID of the category that we are importing into first):

PowervRO17

Or with a bit of extra work, we can import all of the exported workflows:

PowervRO18

 

Obtaining vRO Workflow State and Result with PowervRO

In the previous episode we looked at how to invoke a vRO workflow with PowerShell, via PowervRO and the Invoke-vROWorkflow function. Once you have kicked the workflow off you are likely to then want to find out the state of the workflow, when it has finished and any output from the workflow. Here’s how to do this via PowervRO.

Check the Workflow State:

First of all, we need to identify which execution of a particular workflow we want to check the state of. In GUI terms this means “which one of these?”:

PowervRO11

Typically, we will want to look at the active one, i.e. the most recent. We can find that as follows:

You can see there is a State property which gives a basic indication of what’s going on. We can find out more details with Get-vROWorkflowExecutionState:

Get the Workflow Result

If the workflow has Output parameters set we can retrieve the results with Get-vROWorkflowExecutionResult. In this example the workflow will generate a random number and include it as an output:

PowervRO12

PowervRO13b

We simply pipe the output of Get-vROWorkflowExecution into Get-vROWorkflowResult ūüôā

Automate vRealize Orchestrator with PowerShell: Introducing PowervRO

For¬†the PowerCLI book 2nd Edition¬†I helped put together a chapter on vRealize Orchestrator. Most of the chapter was focused on running PowerShell scripts from vRO, which was something I’d had a fair bit of experience with in projects I had been on and also thought would be what most people reading would be interested in. At the end of the chapter I added a few functions using the vRO REST API to run things in vRO from PowerShell as a bit of an after-thought.

I was quite surprised when during a review phase my co-author Brian Graf suggested swapping the content of the chapter around because he thought there might¬†be more interest in driving vRO with PowerShell, rather than having vRO execute PowerShell scripts. That didn’t quite happen due to time constraints on the book, but I kept that thought in mind having been sparked by the interest.

While putting together PowervRA I had some thoughts about expanding on what I had done in the book around PowerShell and vRO, improving what I had done for the book based on some feedback and incorporating everything we had learnt while putting that toolkit together. Thankfully Craig was up for another project and so PowervRO was born!

Over the course of the last two months or so we have put a toolkit of PowerShell functions together covering a significant portion of the¬†vRO REST API and thankfully it has been a lot more pleasurable than what we have experienced with PowervRA¬†¬†ūüėČ

Initial Release

For the initial release we have 59 functions available covering a sizeable chunk of the vRO REST API. Compatibility is currently as follows:

vRO: versions 6.x and 7.0.1

PowerShell: version 4  and above is required.

You can get it from Github  or the PowerShell Gallery

We have provided an install script on Github if you are using PowerShell v4. If you have v5 you can get it from the PowerShell Gallery with:

Getting Started

Get yourself a copy of the module via one of the above methods or simply downloading the zip, unblocking the file and unzipping,  then copying it to somewhere in your$env:PSModulePath.

PowervRO01

PowervRO02

Import the module first:

You can observe the functions contained in the module with the following command:

Before running any of the functions to do anything within vRO, you will first of all need to make a connection to a vRO server. If you are using self signed certificates, ensure that you use the IgnoreCertRequirements parameter. :

You‚Äôll receive a response, which most importantly contains an encoded password. This response is stored automatically in a Global variable:¬†$vROConnection. Values in this variable will be reused when using functions in the module, which basically means you don‚Äôt need to get a new encoded password or server URL¬†each time, nor have to specify it with a function ‚Äď it‚Äôs done for you.

Each of the functions has help built-in, alternatively you can visit this site http://powervro.readthedocs.org

Example Use Case: Invoke a vRO Workflow with a Single Parameter

Having made a connection to¬†vRO, it‚Äôs now time to start using some of the functions from the PowervRO module. To¬†invoke a vRO workflow we need to determine the Id of the workflow and whether the workflow requires¬†any parameters to be sent in order to run it correctly. Let’s look at an example of a workflow Test02.

The Id is 5af6c1fd-3d12-4418-8542-0afad165cc08

PowervRO03

The workflow has a single parameter, a, which is a String:

PowervRO04

The schema of the workflow is very simple, there is a single Scriptable Task which logs what the input parameter a was:

PowervRO05

PowervRO06

We can get the ID of a vRO workflow with Get-vROWorkflow:

and we could use that ID directly with Invoke-vROWorkflow. However, we made this easier by adding Pipeline support to Invoke-vROWorkflow, so all you need to do is this:

And here’s the result:

PowervRO07

Example Use Case: Invoke a vRO Workflow with Multiple Parameters

So that was fine for a single parameter, but what to do if the workflow has multiple parameters? The parameter set for Invoke-vROWorkflow that we used in the previous example only supports a single parameter.

Let’s look at another example. The workflow Test03 has two inputs, a and b of different types, String and Number:

PowervRO08

Again it has a single Schema element, which does the following:

PowervRO09

Step forward New-vROParameterDefinition. We can use a combination of this function from PowervRO and Invoke-vROWorkflow and the Parameters parameter to submit the request to run the vRO workflow supplying multiple parameters.

To do this, create an array of parameters using New-vROParameterDefinition and supply them to Invoke-vROWorkflow:

and here’s the result of the workflow execution:

PowervRO10

Stay tuned for more examples on using PowervRO, you can also follow @PowervROModule for updates ūüôā

Importing a vRO Package via the API – tagImportMode

I like the new Swagger UI for the vRO API, it makes it really easy to use:

tagImportMode01

While using it to figure out some stuff around importing a package, I hit an issue with the tagImportMode parameter:

tagImportMode02

Depending on which option selected, the following additions to the URL were listed in the documentation as follows:

https://vroserver.fqdn:8281/vco/api/packages?overwrite=false&importConfigurationAttributeValues=true&tagImportMode=Do%20not%20import%20tags.

https://vroserver.fqdn:8281/vco/api/packages?overwrite=false&importConfigurationAttributeValues=true&tagImportMode=Import%20tags%20and%20overwrite%20existing%20values.

https://vroserver.fqdn:8281/vco/api/packages?overwrite=false&importConfigurationAttributeValues=true&tagImportMode=Import%20tags%20but%20preserve%20existing%20values.

However, none of these choices seemed to work, just resulted in 400 (Bad request). Some trial and error followed with different possible combinations, but eventually I found two of them documented in the Developing a Web Services Client for VMware vCenter Orchestrator guide for vCO 5.5.1 and so was able to guess the third.

&tagImportMode=DoNotImport

&tagImportMode=ImportAndOverwriteExistingValue

&tagImportMode=ImportButPreserveExistingValue

Panini Euro 2016 Sticker Tracker

I was using the Panini iPhone app to track our Euro 2016 sticker collection until it helpfully lost all of the data I had input. So I went back to an Excel workbook I had created for previous tournament collections and thought it would be worth sharing it.

On the data sheet track via a colour which stickers you have got, then you can easily see which ones you still need.

Euro201601

On the Swaps sheet, list out your swaps:

Euro201602

Then on the Analysis sheet you will get some figures and graphs to track your collecting progress:

Euro201603

Euro201604

 

You can download the Excel workbook from here.

PowervRA 1.2.2 with Tested Support for vRA 6.2.4

One of the things we did for the 1.2.2 release of PowervRA was to test all of the functions against a vRA 6.2.4 deployment. Now that we have created Pester tests for all of the functions, it is quite straightforward for us to test against different vRA versions.

While we had initially targeted vRA 7+ because of the better API support, we know that currently the majority of installations out there are 6.x.x. So we are happy to confirm that 58 of the functions work fine with 6.2.4, which was a slightly higher figure than I was expecting.

All of the functions which will not work pre v7 have been updated to include an API version check and will exit the function with a message to reflect that if you try to use  them with 6.x.x, e.g.

Get-vRAContentPackage is not supported with vRA API version 6.2

v6Support01

 

Using Pester to Automate the Testing of PowervRA

Learning Pester has been on my list to get done this year and while working on PowervRA I finally had a real project that could make significant use of it. Being able to automate the testing of each PowerShell function means that we can quickly test the impact of any changes to a function. Also, it means that we can test the whole module full of functions against new (and potentially old) versions of vRA.

There is a very useful introduction to Pester on the Hey Scripting Guy site and that is what I used to get started with it.

So after we released the first version of PowervRA I set about creating a test for each function in the module – and here is where I learned my first mistake, although to be fair I knew I was making this mistake during the initial development of PowervRA. With 70+ functions in the module at that time, I needed to write a test for each of them. So after the initial interest in learning how Pester works, I then had the boring task of writing all of the tests.

What (I knew) we should have done, was write a Pester test for each function during (or before) the development of that function. Consequently, it would not seem like such a laborious task to make them. So going forward that’s what we are doing each time we create a new function.

So what does a test look like? Well here is one for Reservation Policies:

You should see that each set of tests is grouped in a Describe section. Each test starts with the It keyword, then typically we do something and check a property of the object returned afterwards. The Should keyword enables us to specify something to check the result against. As you can see Pester has been made so that the tests should be quite nicely readable.

We then follow a pattern of New-xxx, Get-xxx, Set-xxx, Remove-xxx, which all being well leaves us with a clean environment after the tests.

For these tests, we want to check each function against a real life instance of vRA, consequently we need some values. I’m not sure if this is the best way to do it, but for the time being we’ve abstracted the data out of the test files and into a JSON file of variables. This means if we want to run the same tests against a different instance of vRA, we just need to change some of the values in that file. (There is a way to carry out Unit testing in Pester using¬†Mocking¬†which we may visit at some point)

An example of how we can use them is as follows. We can fire the tests against a vRA 7.0 instance and get the following results:

Pester02

By changing some of the variables in the JSON file, we can then fire the same tests against a vRA 7.0.1 instance:

Pester03

and so we can tell with a good degree of confidence that nothing is broken for PowervRA between the two versions. As you can see we can run 81 tests in 60 – 75 seconds, which is pretty cool ūüôā

Craig and I have discussed that we are only really scratching the surface with the tests so far and we could probably take someone onto the project who is solely dedicated to the testing (If you are interested, let me know ūüôā ¬†). For example, for the time being we are only checking one property per New-vRAxxxx thing which gets created, ideally we should really test every property. For now though, what we have got so far is a big step forward and I’m looking forward to learning more about Pester.

If you want to check out what we have done with the tests you can find them here.

Import a Package from a Folder in vRO 7.0.1

vRO 7.0.1 in Design mode contains a new toolbar button in Packages; Import package from folder:

ImportFromFolder01

Previously it was possible to export a vRO package to either a zip file or directly to a folder, but only import back from a zip file.

For example, take the following package com.jm.test, which contains 3 workflows and 1 action:
ImportFromFolder02ImportFromFolder03ImportFromFolder04

Exported to a folder test, we get the following:

ImportFromFolder05 ImportFromFolder06 ImportFromFolder07

 

Now in a clean vRO server, I currently do not have those workflows:

ImportFromFolder07b

If I select the Import Package from folder button, I can browse to the folder contained the previously exported to a folder package:

ImportFromFolder08

Then the process to import the package is the same as in the previous vRO versions when importing from a zip file:

ImportFromFolder09

ImportFromFolder10

and now I can use the workflows and action

ImportFromFolder11

ImportFromFolder12

 

Not only is this very handy, it is potentially significant, because it may make it slightly easier to integrate vRO workflow development with source control systems.

vRO requestCatalogItem from vRA Action – Available Properties

The vRO Action requestCatalogItem in the com.vmware.library.vcaccafe.request folder can be used to programmatically request an item from a vRA Catalog.

RequestCatalogItem01

One of the inputs is a properties object which permits you to dynamically make changes to settings configured within the Catalog Item you are deploying from. So say for instance the Catalog Item maps to a Blueprint configured with 1 vCPU, you could change this at request time to be 2 vCPU – which for instance might lead you to needing to maintain fewer Catalog Items.

It’s possible that it exists already, but I haven’t been able to find where the entire list of available properties that you can use are documented. Many of those starting VirtualMachine. or VMware. can be found in the vRA Custom Properties guide, so I’m not going to list them all here. However, not every available property in those ranges¬†actually appear to be in that guide.

So I have decided to maintain a list here garnered from various sources, including a few common ones from the Custom Properties guide. If you know of any others not in the Custom Properties guide, then please leave a comment and I’ll add them:
provider-blueprintId: vRA Blueprint
provider-ProvisioningGroupId: Business Group

provider-VirtualMachine.CPU.Count:
provider-VirtualMachine.Memory.Size:
provider-VirtualMachine.NetworkX.NetworkProfileName: Network profile for NIC 0
provider-VirtualMachine.NetworkX.Name: Network Name (portgroup) for NIC 0

provider-VirtualMachine.DiskX.IsClone:
provider-VirtualMachine.DiskX.Size:

provider-VirtualMachine.DiskX.StorageReservationPolicy: vRA Storage Reservation Policy
provider-VirtualMachine.DiskX.StoragePolicy.FriendlyName: vCenter Storage Policy
provider-VirtualMachine.DiskX.StoragePolicy.vCenterStoragePolicy: vCenter Storage Policy

provider-VirtualMachine.LeaseDays

provider-VMware.VirtualCenter.Folder: Virtual Center folder
provider-Cafe.Shim.VirtualMachine.TotalStorageSize:
provider-Cafe.Shim.VirtualMachine.Description: Description
provider-Cafe.Shim.VirtualMachine.AssignToUser: vRA Machine owner
provider-Cafe.Shim.VirtualMachine.NumberofInstances: Number of VMs to deploy
provider-CustomPrefix
provider-__reservationPolicyID: vRA Reservation Policy

 

Create a vRA Tenant and set Directory and Administrator Configuration with PowervRA

One of the reasons behind creating PowervRA was as a consultant I often have the need to quickly spin up vRA Tenants and / or components within those Tenants to facilitate development or testing work of other things I am automating. PowervRA contains three functions, which when joined together would make a basic vRA Tenant available for use: New-vRATenant, New-vRATenantDirectory and Add-vRAPrincipalToTenantRole.

The following code example demonstrates how to use these in conjunction with each other to make a vRA Tenant (make sure to first of all have generated an API token with Connect-vRAServer with an account that has permission to create a vRA Tenant):

Note that since New-vRATenantDirectory has a lot of parameters, I have taken advantage of the ability to instead provide the necessary JSON text directly to it.

The result is a fresh vRA Tenant with a Directory configured and admin accounts assigned to both the Tenant Admins and Infrastructure Admins roles:

CreateTenantPowervRA02

 

CreateTenantPowervRA01