vRA Developer: Part 1 – IaaS & Understanding the Entity Framework

vRealize Automation 7.x is currently in a sort of ‘split brain’ where there exists two data models which can be used to interact with vRA objects. One is objects that are backed by the Cafe appliance / PostgreSQL database and the other which uses the older, entity framework (IaaS servers).

This post is going to focus on the entity framework, which is still very relevant when working with this version of vRA. There are many things that still do not exist in the newer data model, such as custom properties and data collection. I still see vRO/vRA developers struggle with this, so I hope to help improve the situation.

The Entity Framework

When I first worked with vRA, I struggled to understand how objects were stored and manipulated in the database. I often came across a common object class called an entity. I later discovered that all objects stored in the vRA database are considered ‘entities‘. This is because vRA has been developed with Microsoft’s “Entity Framework“. A brief description of this taken from http://www.entityframeworktutorial.net

The Microsoft ADO.NET Entity Framework is an Object/Relational Mapping (ORM) framework that enables developers to work with relational data as domain-specific objects, eliminating the need for most of the data access plumbing code that developers usually need to write. Using the Entity Framework, developers issue queries using LINQ, then retrieve and manipulate data as strongly typed objects. The Entity Framework’s ORM implementation provides services like change tracking, identity resolution, lazy loading, and query translation so that developers can focus on their application-specific business logic rather than the data access fundamentals.

Entity framework is an Object/Relational Mapping (O/RM) framework. It is an enhancement to ADO.NET that gives developers an automated mechanism for accessing & storing the data in the database.

The ‘domain-specific objects‘ reference is key here and are defined as:

Domain objects are represented by entities and value objects that exist within a domain layer. These objects contribute to a common model and are exposed as a data service, which is also provided by the entity framework.

The entity framework is a layer of abstraction that sits on top of the underlying relational database (SQL Server). This abstraction allows developers to work within a standard framework. Yes, you could run SQL queries on the underlying database directly, but this gets really ugly and isn’t supported.

LINQ is Microsoft’s .NET Language-Integrated Query (language).

What is also important to note is that entities follow some form of continuity and identity (i.e. they must all have certain attributes, such as an ID field or callable methods). This standard allows for a consistent interaction with the domain objects.

In the case of vRA, all domain-level objects (entities) are provided under the ‘ManagementModelEntities.svc‘ data service model. Within this data service model, entities are organised into their own ‘tables’, known as ‘Entity Sets’, and entities can also link to (relate to) other entities. Getting an understanding of the entities will make your life as a vRA/vRO developer so much easier. Continue reading

vRA Developer: Part 2 – Dynamically Discover vCAC and vCACCAFE endpoints in vRO

When I work with endpoints in vRO, I like to use actions to discover these instead of hard coding them as attributes or within configuration elements. Hard coding of these endpoints requires manual configuration steps when moving code between environments, which is not ideal. I felt it would be a good idea to include this post early on within this series, as these hosts are often dependencies when working with a lot of my code.

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

Discover vRealize Automation Infrastructure (vCAC IaaS) Endpoint

You will generally only have a single vCAC IaaS endpoint in your vRO inventory. I have never worked in an environment where there was more than one. Therefore, the action I have created below requires no inputs and will attempt to discover this single vCAC IaaS endpoint. If you have more than one host for some reason then it should be fairly easy to incorporate this.

Log output:

Continue reading

vRA Developer: Part 3 – Performing CRUD Operations on IaaS Entity Objects

In a previous post vRA Developer: Part 1 – IaaS & Understanding The Entity Framework I detailed what the Entity Framework is and how objects and their properties could be discovered using an application called LINQPad.

This post is going to detail how we can interact with the IaaS servers and work with the objects within the Entity Framework. I have also written a number of actions that provide a standard interface to use when working with the entities and perform CRUD (Create, Read, Update, Delete) operations on them. 

Note: these actions are designed to be used with wrappers for your code (i.e. other actions performing a task, which call these actions) and not directly in your workflows (although there is no real harm if you want to, it’s just cleaner not to). Continue reading

vRA Developer: Part 4 – Working with vCAC Virtual Machine Entities

In the first post in this series, vRA Developer: Part 1 – IaaS & Understanding The Entity Framework I detailed how you can view the vCAC entities and their associated properties. In this post I am going to cover how you can find a virtual machine entity using different property references and get/update their properties in your vRO workflows. I had intended to provide a single post for this, but felt it would be useful to provide a number of posts, for each specific vCAC entity type. In this post I am going to be looking at the vCAC virtual machine entities.

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

Finding vCAC Virtual Machine Entities

When I need to find a vCAC virtual machine entity, there are 4 search references that work well for all of my use cases. These are to search by:

  • VirtualMachineID – The entity ID.
  • VirtualMachineName – The VM name. Take caution as it’s possible to have duplicate entities with the same VirtualMachineName.
  • VMUniqueID – The unique identifier for the vm (i.e. vCenter VM instance UUID).
  • ExternalReferenceId – The external reference id (i.e. vCenter VM Id (MoRef)).

I have provided all the Actions below which perform these searches and an example log output for each.

Find Virtual Machine By Entity Id

The following code can be used to get the virtual machine entity by its entity id.

Log output:

Continue reading

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.

Log output:

Continue reading

vRA Developer: Part 6 – Working with vCAC Virtual Machine Custom Properties

In part 4 and part 5, I covered a lot of ground on how to work with vcac virtual machine objects, such as getting property values and discovering relationships to other entities. This post will continue exploring vcac virtual machines and will focus on custom properties.

Custom Properties are key/value pairs of data that are associated with the virtual machine. There are many default/built-in custom properties that provide the compute cluster, storage cluster, disk, cpu, network information and much more.

It’s also possible to create your own custom properties and associate these with your virtual machine deployments. This allows great flexibility as you can apply any key/value to your deployments and use this information in your workflows. An example might be to set a site identifier that associates the virtual machine to a specific site.

VMware provides a Custom Properties Reference, which details all the built-in custom properties that are available.

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

Retrieving Custom Properties Assigned to a Virtual Machine

There are two main ways to retrieve the custom properties that have been associated with a virtual machine deployment. The first, is during the build process, where an Event Broker Subscription is used to call a vRO workflow, to perform some task. The second, is by reading the custom properties from the vcac database (via the entities) for those that are related to the virtual machine.

Here is an example of a default set of Custom Properties associated with a deployed virtual machine:

The first set are prefixed with a double underscore (__), which denotes that these are ‘hidden’ properties that are used by the system and provide object references to the reservation and the request (note that these properties will not be referenced in the official VMware Custom Properties Reference).

The remaining properties are the key/values associated with the virtual machine and can provide cpu count, amount of assigned memory, used storage, etc. and any user-defined custom properties that you have created. Unlike the hidden properties. you will find a reference to all of these in the VMware Custom Properties Reference.

One important thing to note, is that when you are working with custom property values, these are always returned as a string, regardless of what data is being stored. I.e. if a custom property has a value of ‘false’, this is the literal string “false” and not Boolean false. Continue reading