Code snippets : Using vCloud Director object metadata

Setting metadata on vCloud Director objects is a convenient way to extend their properties with whatever information you need to attach to these. This is very useful to include information on the object lifecycle or to reference other objects. For example I like to reference the vApp Template a vApp was issued from with adding a "vAppTemplateReference" metadata. Another use of the metadata is that you can search for these using the query service.

The vCloud DIrector plug-in has built in workflows for managing custom properties on vApp and VMs (storing these in the productSection if the OVF) but these are not the same as the metadatas. The metadatas can be applied to a lot more objects such as VDC, storage profile, catalog, catalog item, disk, Org VDC network, media, external network).

This article shows how to use these in vCloud Director 1.5 and in 5.1.

The functionality we will be looking for is simple: an action to set a metadata string entry on an objet and one to get it back.

Inputs for the setMetadataStringEntry action:

  • object of type "any"
  • key "string"
  • value "string"

Inputs for the getMetadataStringEntry action:

  • object of type "any"
  • key "string"

vCloud Director 1.5.

vCloud Director 1.5 has a very simple metadata API limited to string values

setMetadataEntry action

Which returns a vCloud task.

getMetadataEntry action

1
2
3

var metadata = object.getMetadata();
var entries = metadata.getEntries();
return entries.get(key);

Which returns the value if present.

vCloud Director 5.1

vCloud Director has extended the metada with typed entries (number, string, boolean, date) and also with access control. You can read all the details in the vCloud API programming guide.

All these new features come with a drawback : the API has changed and the code above will not work. This is what happened to me and I thought it would be worth sharing how I adapted it to work with vCloud Director 5.1.

We will assume we still want to use a string as the value. If you need one of the other type it will be easy to adapt.

setMetadataStringEntry action

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var metadata = object.getMetadata();

var vclMetadataStringValue = new VclMetadataStringValue() ;
vclMetadataStringValue.value = value;

var vclAbstractValueObject = new VclAbstractValueObject();
vclAbstractValueObject.setValue(vclMetadataStringValue);

var vclMetadataEntry = new VclMetadataEntry();
vclMetadataEntry.key = key;
vclMetadataEntry.typedValue = vclAbstractValueObject;

System.log("Setting key " + key + " with value " + value);
return metadata.updateTypedEntry(vclMetadataEntry);

Which returns a vCloud task.

getMetadataStringEntry action

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var metadata = object.getMetadata(); //All objects that support metadata return something, even if there are no metada yet

var metadataEntries = metadata.getTypedEntries().enumerate();
var value = null;
for each (var metadataEntry in metadataEntries) {
    if (metadataEntry.key == key) {
        value = metadataEntry.typedValue.getValue(new VclMetadataStringValue).value;
        System.log("Got key : " + key + " with value : " + value);
        break;
    }    
}

return value;

Which returns the value if present.

Testing the actions

To test these actions you can create a workflow with as input an object (for example a vAppTemplate), a key and a value. You can either drag and drop the two actions or create a workflow per action. As long as you set the metadata before you get it it should work. Do not forget to link the inputs and create the attributes. Also do not forget to add a "Wait for a task" workflow right after setting the metadata. It should look like this:

alt

The output of the getMetadata action should of course return the same of what you entered in the workflow input.

Package

The actions above are available as an instllable package: