Friday, May 3, 2013

vCAC Property Dictionary: Customize Service Requests with Dynamic Menus

//Update// - this procedure also works with vCAC 6.x. The UI will look different, but same concepts apply. The property dictionary in vCAC 6 is located at Infrastructure (tab) --> Blueprints...

In a previous post I discussed the benefits of utilizing vCloud Automation Center's Property Dictionary to add input options during the application request process. This is one of the quickest ways to add some flare (and serious functionality) to the application request and allows users to have a little more granularity in the service selection process. The Property Dictionary - and custom properties in general - also help drive down the number of Blueprints thanks to the logic that can be baked right into the process.

Let's review (from previous post)

In addition to creating a custom property, which can trigger external actions (workflows), you can create property definitions that utilize vCAC's built-in reserved custom properties, which can be used take a user's input and apply it to an existing custom property - think of it as an answer file of sorts. For example, a drop-down list that presents the networks available to a given Provisioning Group and allowing users to select a preferred network. The property dictionary can also be used to build relationships between parent and child definitions to provide a more dynamic and nested functionality - the user selects a location ("Datacenter A", parent) and, based on that selection, only appropriate networks ("NetA", "NetB", "NetC", children) dynamically become available. The result is an application that gets deployed to Datacenter A using Network B. Throw a storage selection option in there with the same Datacenter relationship rule and now you've got a fine balance of policy-based controls and a dynamic user-experience...
Application Request - Resource Selection

Use the step-by-step instructions below build this exact use case in your implementation of vCloud Automation Center. The assumption here is that you’ve got a working vCAC environment. If not, start with my vCAC 5.1 Detailed Installation Guide. Also, these steps are all built on version 5.1 but will also work on 5.2.

Here’s a shot of our starting point - the plain old “out of the box” request

Building the Logic

The objective here is to accomplish this use case by only using vCAC’s built-in functionality (the "out of the box" stuff). This will be accomplished primarily by leveraging the Property Dictionary and vCAC's reserved custom properties. The only time you'll ever have to leave the admin UI is to define the DataCenter locations by using an XML file located on the vCAC server. We’ll start there…

1) Add DataCenter Locations

The Locations property is a reserved custom property that will allow you to tie compute resources to named locations. For example, you can define two or more geographically-separated vSphere compute resources and use the Location property to tie those resources to a given location (physical, logical, whatever). These locations are defined in the DataCenterLocations.xml file on the vCAC server. Once this is done, a drop-down menu with available locations will automatically show up in the user portal during a provisioning request. But first, you would have to enable the “Display location on request” option for each Blueprint…but not so fast, we’re taking a different approach.

There’s a caveat with this and our objective – we cannot create a child/parent relationship with the built-in Location property menu. To accomplish the task at hand, we’ll need to override the Location custom property and define our own using the Property Dictionary. We will then be able to tie child selections (Network and Storage) to the selected Location. Make sense? Let’s configure…

> Locate and open (edit) the DataCenterLocations.xml file located in c:\Program Files (x86)\DynamicOps\DCACServer\WebSite\XmlData\  (be sure to make a backup copy first):

> Replace the existing sample locations with your desired named locations. In this example my locations are “Fairfax Lab” and “Reston Lab”. These are separate vSphere clusters in the same physical environment (managed by the same vCenter Endpoint).

> Save the changes (NOTE: you may have to restart the vCAC Service before these locations are available).

2) Associate Compute Resources to a Location

Once your DataCenterLocations.xml file is complete, we need to tie the specified named locations to actual Compute Resources in vCAC. This creates a logical binding of the location and available resources:

> From the “Compute Resources” section, hover over an available compute resource and select “Edit” (NOTE: do this only for the compute resources you want tied to Locations – this use case uses 1-to-1 relationships between resources and locations)

> From the “Location” drop-down menu, select the appropriate location for this Compute Resource. Here we’re tying resource “Cloud Resources” to Location “Fairfax Lab”:

> Click OK to save 

> Do this for each Compute Resource – here I tie resource “Management” to Location “Reston Lab”:

> Click OK to save

At this point you can enable the Location drop-down by enabling the “Display location on request” for individual Blueprints. But as I mentioned above, we’re not stopping here – we have to add some additional logic to build the child relationships to the Datacenter location per this use case.

3) Build the Property Definitions

Next step is to define the property definitions that will be used to accomplish our use case. We’ll be using three built-in reserved custom properties to define Location, Storage, and Network bindings. To learn about all the reserved custom properties that ship with vCAC, see the vCAC 5.1 Operations Guide.

3a. Location: Vrm.DataCenter.Location

The reserved custom property “Vrm.DataCenter.Location” is used here to override the built-in Location property so we can create the necessary parent/child relationship in the request screen. It is tied to the same DataCenterLocations.xml file and will enable the same functionality (and gives us a bit more control). 

> From the “Enterprise Administrator” section, select “Property Dictionary” 

> Select “Add Property Definition” to create the first definition

> Enter the following in each of the fields:
    -- Name: Vrm.DataCenter.Location
    -- Display Name: Select a DataCenter (this is what shows up in the request window)
    -- Description: Enter something descriptive
    -- Control Type: DropDownList
    -- Required: YES (checked)

> Click the green check to save 

> Select “Edit” under the “Property Attributes” column 

> Select "Add Property Attribute"

> Enter or Select the following in the available fields:
    -- Type: ValueList
    -- Name: Vrm.DataCenter.Location
    -- Value: Fairfax Lab, Reston Lab (NOTE: the values here are a comma-separated list of available options that will show up in the associated drop-down menu during a provisioning request. This list must match the entries in the DataCenterLocations.xml file defined earlier. Spaces are acceptable.) 

> Click the green check to save this attribute

> As an optional step, you can add the Help Text attribute to this definition, which will show up in the request portal when users hover over the (?). This can display whatever you think would be helpful for the user.

> Click on the green check to save

> Select OK to apply 

3b. Storage: VirtualMachine.Storage.Name

The reserved custom property “VirtualMachine.Storage.Name” defines which storage path (datastore) a machine will be deployed to. We’re going to define a list of available storage paths to allow users to select a preferred location, overriding vCAC’s own placement algorithm. For our use case, the list of storage paths will be tied to the datacenter location parent. Considering the Vrm.DataCenter.Location custom propery is tied to a specific Compute Resource, we need to make sure only storage paths that are available to that resource are available for selection. In fact, the storage paths we define here need to be available to the Resource Reservation allocation of the Compute Resource (this applies to Network Paths as well). To recall which storage and network resources have been allocated, check the “Resources” tab for each reservation.

Here is a snapshot of the “Resources” tab for the “Management-Res-1” reservation, which is an allocation of compute, storage, and network resources from the parent Compute Resource “Management” and is now tied to the DataCenter Location “Reston Lab” defined previously. As you can see, there are three storage paths enabled for this reservation – ds01_ssd, ds02_sata, and ds03_sata. We can use one or all of the available storage paths.

Likewise, here are the resources available to the “Cloud Resources-Res-1” Reservation, which is an allocation from the Compute Resource called “Cloud Resources” and tied to the “Fairfax Lab” location:

Laying it all out might be helpful:

> From the Property Dictionary section, select "Add Property Definition"

> Enter the following in each of the fields:
    -- Name: VirtualMachine.Storage.Name
    -- Display Name: Select Desired Storage
    -- Description: Enter something descriptive
    -- Control Type: DropDownList
    -- Required: YES (checked)

> Click on the green check to save

> Select "Edit" in the "Property Attributes" column for the VirtualMachine.Storage.Name property

> Create a HelpText attribute similar to the one above (optional)

Now we need to build a relationship between this definition (child) to the DataCenter (parent). To do this, we'll need to add a "Relationship" attribute...

> Select "Add Property Attribute"

> Enter or Select the following in the available fields:
    -- Type: Relationship
    -- Name: Vrm.DataCenter.Location
    -- Value: Vrm.DataCenter.Location

> Click the green check to save this attribute

Now comes the fun part. In order dynamically display the appropriate storage paths based on the DataCenter parent selection, we'll need to create a Value Expression to define the logic. The expression is basically an 'if x then y' statement built in XML that ties all the logic together. The vCAC 5.1 What's New guide provides a sample expression that can be used as a baseline. Here is the XML file that I used in for my environment:

The XML basically defines the relationships each resource tier...
  • The first value, "FilterName", is the parent object - the Vrm.DataCenter.Location property
  • "FilterValue" is associated with the ValueList we created when we defined the Vrm.DataCenter.Location attributes. This must match the named values in that list (also defined in the DataCenterLocations.xml file edited in Step 2).
  • "Value" is the child object which corresponds with the available Storage Path options. Since we want the available storage paths to be dependent on the DataCenter selection (Reston Lab or Fairfax Lab).
The XML lists all the possible if/then combinations. Once the list is complete, you'll have to remove all the line breaks and collapse the entire thing into a single line before pasting it into vCAC. The XML file above turns into this (the text is wrapped):

> Back in the VirtualMachine.Storage.Name definition, select "Add Property Attribute"

> Enter or Select the following in the available fields:
    -- Type: ValueExpression
    -- Name: Storage
    -- Value: [paste single-line XML from above]

The final config should look something like this:

3c. Network: VirtualMachine.Network0.Name

The steps to create the network logic is almost identical to building storage -- except you'll be using the names of the network paths and binding them to the VirtualMachine.Network0.Name reserved custom property.

> From the Property Dictionary section, select "Add Property Definition"

> Enter the following in each of the fields:
    -- Name: VirtualMachine.Network0.Name
    -- Display Name: Select Desired Network
    -- Description: Enter something descriptive
    -- Control Type: DropDownList
    -- Required: YES (checked)

> Click the green check to save this attribute

> Select "Edit" in the "Property Attributes" column for the VirtualMachine.Network0.Name property

> Select "Add Property Attribute" (1 of 3)

> Create a HelpText attribute (optional)

> Click the green check to save this attribute

> Select "Add Property Attribute" (2 of 3)

> Enter or Select the following in the available fields:
    -- Type: Relationship
    -- Name: Vrm.DataCenter.Location
    -- Value: Vrm.DataCenter.Location

> Click the green check to save this attribute

> Select "Add Property Attribute" (3 of 3)

> Enter or Select the following in the available fields:
    -- Type: ValueExpression
    -- Name: Storage
    -- Value: [paste single-line XML]

Should be looking something like this:

> Click OK to apply these attributes

4) Create a Property Layout

Now that we've got our properties all laid out, we need to make sure they show up in logical order during a request. For example, "Select a DataCenter" should be first on the list, followed by "Select Desired Storage" then "Select Desired Network". To ensure this is the case, we'll create a Property Layout:

> In the Property Dictionary section, select "Add Property Layout"

> Name the Layout and add a description that makes sense

> Click the green check to save the Layout

> Select "Edit" in the Property Instances column

> In the "Order" column, enter "1", then select the Vrm.DataCenter.Location property from the "Property Definition" drop-down menu

> Do this for each of the properties...they will be displayed in numerical order

> When complete, select "OK" to apply the Layout

5) Apply Custom Properties to Blueprints

Now that we've defined all the properties, it's time to apply these policies to Blueprints. You can choose to them to just one or all of your available vSphere Blueprints. This will allow you to be selective with which applications you will allow users to define specific storage and network paths, giving you more granular controls and options. In this section, we'll pick a predefined Windows 2008 R2 Blueprint and assign the appropriate properties to it.

> From the "Global Blueprints" admin section, locate the Blueprint you want to add the menus to and select "Edit" from the submenu (or simply click on the blueprint name). In the case, we're customizing the "vSphere - Windows 2008 R2 x64 Gold" Blueprint

> Select the "Properties" tab

> Select "New Property"

> Create a new property and enter the following values for each of the properties created previously as seen below. The "Name" MUST match the property name and is case sensitive. There are no additional values to define at this point. Be sure to check "Prompt User" for each...

> Add the Layout profile we created previously by adding the "VirtualMachine.Request.Layout" property and entering the Layout name in the Value column ("MyLayout-1" in this example). Do not enable "Prompt User" for this.

6) Deploy and Enjoy...

> Log into the vCAC Self-Service Portal as a Provisioning Group user (use an account with access to the Blueprint we just added the custom properties to)

The new menus should be available under the "Additional Settings" side tab. Selecting a parent DataCenter will dynamically provide the appropriate child options. Once submitted, the appropriate resources will be allocated to the Windows machine being deployed...

Fairfax Lab menus:

Reston Lab menus...

Troubleshooting Note: if the drop-down menues don't have any value, you'll want to check the XML file and make sure there are no typos, missing brackets, collapsed to a single line, etc. It has to be perfect for this to work.

Now that you've been through this exercise, consider the possibilities with how you can customize not only the user experience, but also how infrastructure behaves based on user input. Also be sure to read the vCAC 5.1 What's New Guide and Operations Guide for more details on Property Dictionary and the available Reserved Custom Properties.

Enjoy! (and good luck)



  1. Really useful. I've got only one question. Can you tell me why the field "Location" is not displayed in your "Request new machine" screenshot while it's displayed in mine? I would like to get rid of Location, it's a duplicate of "Select a Datacenter".


    1. I wonder about this too. Location is not shown in the vCAC portal when you don't check the appropriate checkbox, but it's shown in the SelfService portal always, once the location is defined.

      More so, if a location is not available to a blueprint because there is no available reservation/compute resource for that location, the custom dropdown "Vrm.DataCenter.Location" still shows it.

      So it doesn't actually really replace the "Location" drop-down directly. I could actually just call it "Datacenter" instead of "Vrm.DataCenter.Location" and achieve the same results, which is a bit disappointing. Or am I missing something?

  2. how does the multi data center function handle the blueprints guide to the server template? Does it do a wan based deploy of the virtual machine or do we just need to exactly replicate the template to every data center?

    1. As far I see it, you have two options (as of vCAC 5.2):

      1. You leave the 'CloneFrom' custom property the way you set it in the blueprint and then it will deploy it across WAN if the new location is in a different datacenter (given the network configuration allows that).

      2. You'll make a related drop-down where you force the user to select the template of the respective datacenter you're deploying in. Unfortunately you cannot simply modify a hidden custom property, but you need to force the user to select it, even though there is only one choice available.

  3. Hi,
    I don't get any Location option in vCloud director compute resources.
    I'm able to see it only in vCenter compute resources. Kindly advise.


  4. Great article!

    One thing I'm having a hard time finding information around is the ability to leverage a single Blueprint and attach a drop down list or the ability for an end user to choose from a list of machine prefixes. Is this possible? I can't seem to find any information around whether Machine Prefix has a Blueprint Custom Property that will override what's set in the Machine Prefix drop down as part of the Blueprint design.

    Ideally I want to make my Blueprints as generic as possible and let the end user drive how specific the machine that's provisioned from the Blueprint will be. I'm leveraging network segment, storage type and environment (dev, staging, QA, etc.) from above, but machine prefix is the last part that I need to build into this process so we can standardize naming conventions, based on the deployment type. If I could build the machine name from selected values in the dropdown that would work too, but I don't think that would leverage the prefix incrementing that I'd like to use.

    1. An easy way you can do this is to insert a custom DropDownList ('user-chosen-machine-prefix') so the user can choose from the machine prefixes and then hook into the WFStubsBuildingMachine workflow and then rewrite the hostname according to the user chosen machine prefix. Within the WF you can use sth like this: $MachinePrefix = ($vm.VirtualMachineProperties |? PropertName -eq 'user-chosen-machine-prefix').PropertValue; $vm.VirtualMachineName = $vm.VirtualMachineName($vm.VirtualMachineTemplate.MachinePrefix, $MachinePrefix); $mgmtContext.UpdateProperty($vm); $mgmtContext.SaveChanges();

  5. I was suggested this web site by my cousin. I am not sure whether this post is written by him as no one else know such detailed about my difficulty. You're wonderful! Thanks!

  6. Great post!

    I tried this in my lab without success, but with a minor difference. I was trying to set the network selection with a static property. For example, I want to set the VLAN options based on the customer's vCenter folder, which is set in the Provisioning Group properties. The dynamic list only seems to work if you make another selection in the blueprint, but not if you have a static property.

    Have you seen the same behaviour?

  7. This is really a great post and i implemented it to my test environment to play around a little bit which brings me to one questions:
    Is it possible to automatically set the values for Storage and Networking based on the location? So the user just chooses his location and networking and storage would be automatically selected in the background where the user doesn't have to choose?

    Thanks for reply

  8. Hi,
    i think that the Network part works only if you use DHCP; if you use static ip assignment with network profiles, you need to use VirtualMachine.Network0.ProfileName too.
    the only sets the VLAN tag in the vCenter i suppose.
    any tips?