VMware vRealize Automation Part 9 – Extensibility – Custom Properties & Build Profiles & Property Dictionary

vRA Custom Properties

Custom properties can be used to modify a machine throughout all stages of its lifecycle such as,

  • Request,
  • Provisioning
  • Manage
  • Retire

Custom properties can be used to achieve various objectives such as,

  • Defining the number of cores per socket on a VM blueprint
  • Customising the operating system (hostname, Sysprep information…etc.)
  • Specifying the OU for the machine account to be placed in, on AD
  • Specifying the VM disk type, determine the network placement for a machine
  • Integrating machines with external systems such as Citrix Desktop delivery controller
  • Update external systems once the machine is retired such as cleaning up AD of the stale computer account, clean up DNS, clean up DHCP…etc.

Custom properties can be added to the following sections within vRA (if same property is defined in multiple layers, the order of precedence is as shown below)

  1. Business group
  2. Blueprint
  3. Build profile
  4. Endpoint
  5. Reservation
  6. Compute Resource
  7. Storage

There are 4 main types of custom properties available

  1. Read-Only
    1. Specified value is implemented on the machine and maintained in the vRA database but cannot be changed within vRA
    2. Examples include:
      1. VirtualMachine.Admin.UUID – Specifies the UUID of the machine which cannot be changed
      2. VirtualMachine.Admin.Name
      3. VirtualMachine.Admin.AgentID
  2. Internal
    1. Specified value is maintained only in the vRA database and used purely for information purposes within vRA and has no impact on the machine itself or the virtualisation platform.
    2. Examples include:
      1. VirtualMachine.Admin.Owner
      2. VirtualMachine.Admin.Approver
      3. VirtualMachine.Admin.Description
      4. VirtualMachine.Admin.AdministratorEmail
      5. VirtualMachine.Admin.ConnectionAddress
  3. External
    1. This value is implemented on the machine and maintained in the vRA db. However its not updated in the vRA db when it changes on the machine.
    2. Examples include:
      1. VirtualMachine.Admin.AddOwnerToAdmins – if set to True, owner of the VM added automatically to the local admins group but when revoked, not updated on the vRA db to False (therefore if reprovisioned, the user will be added to the Admins group again)
      2. Hostname (clone)
      3. VirtualMachine.Admin.ClusterName
      4. VirtualMachine.Admin.ThinProvision
      5. VMware.Memory.Reservation
      6. VMware.VirtualCenter.Folder
      7. VMware.VirtualCenter.OperatingSystem
  4. Update
    1. The specified valye is omplemen ted on the machne and is maintained in the vRA db thoughout via data collection when it changes on the machine / virtualisation platform / outside of the vRA. This update is performed by the proxy agent.
    2. Examples include:
      1. VirtualMachine.Admin.Hostname (clone)
      2. VirtualMachine.Admin.TotalDiskUsage
      3. VirtualMachine.Memory.Size
      4. VirtualMachine.Admin.CPU.Count

There are many built in custom properties that belong to these categories and additional custom properties should NOT be created with the same names. The full list of built in custom properties available within vRA 6.2.x are available here.

Build Profiles

Build profile is a collection of properties to be applied to a machine when its provisioned. Built profiles are always read during the machine building process. Build profile provides the ability to group a set of properties so that rather than adding a multiple set of properties to each blueprint, a single build profile can be associated saving time & effort. Build profiles can be created from using default property sets of custom properties (mentioned above). There a number of default property sets that vRA 6.2.1 ships with such as ActiveDirectoryCleanupPlugin. (When you login to vRA portal as the Fabric Administrator and go to Infrastructure->Blueprints->Build profiles, you can see the full list when trying to add a new build profile). Note that build profiles are only applied to blueprints.

Creating a Build profile

  1. Login as Fabric Administrator and go to Infrastructure->Blueprints->Build profiles
  2. Create a new build profile and provide a name. I’m creating a build profile to peform AD cleanup tasks when a computer is retired / destroyed.
  3. Select from the default property set if applicable. Since we already have a default property set for AD cleanup (called ActiveDirectoryCleanupPlugin), im going to be using that here. Select the property set and click load to load the relevant custom properties
  4. Provide the information required for each custom property including the AD user account & passwords with rights to remove computer accounts Build Profiles
  5. Login as Tenant Admin and edit an appropriate blueprint for provisioning a Windows VM that is joined to the domain during the provisioning process and apply the build profile. Associate build profile with BP

That’s it. Every time a VM created using this blueprint is removed / destroyed via vRA (by the user or an administrator), the computer account would now be removed from the AD too. (note that this won’t happen if the VM is removed outside of the vRA management platform, such as directly on the vSphere client.

 Property Dictionary

Property dictionary within vRA is used in tandem with the custom properties and is typically used to achieve the followings.

  • Define characteristics of properties that are used to tailor the behavior of the request user interface
  • Associate a property name with a particular user control, such as a check box, a calendar control, or a drop-down menu
  • Specify constraints such as minimum and maximum values or validation against a regular expression
  • Provide descriptive display names for properties or specify text (for a tool tip or text label) with additional information
  • Designate a property as optional rather than required

Note that property names and values are case sensitive…..!!

Here are different types of property dictionary types available within vRA.

  • Checkbox – Check box for specifying true or false values
    • Example Configuration
      • Create a property dictionary as the fabric admin as follows  CheckBox 1
      • Now attach the property dictionary as a custom property to the blueprint as follows CheckBox 2
      • When you now attempt to provision a machine using the above blueprint, you can see that the defined property dictionary is available (checkbox in this instance)   CheckBox 3
      • Obviously the above example is practically meaningless as the intention was to show how to add a checkbox, not to actually use it for a meaningful purpose. But additional logic can be built in to this checkbox such that if selected, it could perform some additional action during the machine provisioning.
  • DateTimeEdit
    • Can add a date & time edit field to the blueprint
  • DropDown
    • Can add a drop down menu. As an example use case, you can define multiple tiers of storage (Gold, Silver & Bronze) within a drop down list and upon a user selecting the appropriate value from this drop down list during the machine provisioning, the VM can files can be placed automatically on the correct storage tier
  • Integer
    • Defines an integer value
  • Label
    • Provide a label value
  • Link
    • Provide a link. An example would be to direct the user to a 3rd party page where corporate IT policy details are specified which each user requesting a machine provisioning must first read and accept prior to continuing with requesting a machine being provisioned from a blueprint.
  • Notes
    • Notes filed
  • Password
    • Password field
  • TextBox
    • Text box

Now lets take a look at using some of the property dictionary types in a real world scenario.

  • Requirement:
    • You need to enable the business group users who request machine provisioning (using a blueprint) to select the type of the server they are provisioning (Web, App or DB) and depending on the type of the server selected, automatically list all the compatible VM networks available for that server (App-Network-1, App-Network-2 for App VMs, Web-Network-1, Web-Network-2 for Web VMs & DB-Network-1, DB-Network-2 for DB VMs) so that the appropriate network can be selected during the machine provisioning.
  • How to implement using property dictionaries
    1. Login as Fabric-Admin and go to Infrastructure-Blueprint->Property Dictionary and create a property definition called Custom.VM.Category (this could be any name you wish as long as it doesn’t conflict with any of the default custom properties). Select the control type for this property as DropDownList and select required. EX-1
    2. Once created (and the green tic is clicked to complete), click on the edit link under property attribute and create a new property attribute as type ValueList and type the values as Web,App,DB (no spaces in between. Note that these values are case sensitive)   EX-2
    3. Now create another property definition called Custom.VM.Network0 (again, can be any name here as long as there are no conflicts) and select the type as a DropDownList EX-3
    4. Now create an XML file using an XML editor (such as the free XML copy editor) similar to the below, defining the relationship between the 2 property definitions. I’ve attached a link to the file I’ve  created here which you can download. Ensure that you always edit this in an XML editor and not the notepad as due to line breaks & whitespace issues, it will just not work if you copy / paste content within the notepad). Pay attention to the details such as <FilterName> tag which defines the parent property definition name, <FileValue> which defines the parent value (App, Web or DB) and the <Value> which defines the appropriate child value (App/Web/DB-Network-1/2. This XML definition fully defines the relationship between the parent and child properties.  EX-3.5
    5. Now copy the content of this XML definition (from the XML editor, NOT the notepad), go to the property attribute created in the step 3 above (Custom.VM.Network0) and click on the edit button under the property attributes. Create a new property attribute and select type as value expression and paste the XML definition here. Once complete, click the green tic and click ok.         EX-4
    6. Now, create another property attribute here as type relationship and set the value as Custom.VM.Category (Name of the parent property definition created above in step 1) EX-5
    7. Now, add both property definitions as custom properties to a blueprint as follows. EX-6
    8. When you now attempt to provision a machine from this blueprint as a user, you can see that you are bing prompted to select a VM category first (where you have 3 options, Web, App or DB) and depending on which one you choose, the next VM Networks field presents you with the relevant network names to select from. EX-7 EX-8
    9. It should be noted that by selecting the appropriate VM network in above example, it will not automatically connect the machine / VM to that network you select (if that is required, additional work is required including a vRO workflow type of customisation to take the value selected here and match that to a network label available and map the VM’s primary vNIC to it. That is obviously not show in the example here).


There you have it. Custom properties, property dictionaries can be used together to achieve various level of customisation work when defining blueprints and build profiles can be used to group multiple custom properties all together as one, to be attached to blueprints.

Hope this was useful



Next: (Optional) – vRA Part 10 – IaaS Extensibility – Using vRO for Blueprint Customization –>