Complex Content

Many of the data objects required for method invocation consist of XML Schema elements defined as <complexContent> that can encompass many other elements.

For example, the PropertyCollector.CreateFilter method has a spec parameter that must be defined before method invocation. The spec parameter is defined as an instance of a PropertyFilterSpec.

PropertyFilterSpec and Associated Data Objects shows the relationships among several data objects that PropertyFilterSpec consists of.

Figure 1. PropertyFilterSpec and Associated Data Objects

To submit complex data structures such as this to the MOB, start by navigating the vSphere API Reference. Find the PropertyFilterSpec data object. Find the Show WSDL type definition link, and click it to display the XML Schema definition (see XML Schema Definition of PropertyFilterSpec Data Object Type).

XML Schema Definition of PropertyFilterSpec Data Object Type shows that the PropertyFilterSpec data object is a <complexContent> element that extends the DynamicData class with a sequence of two additional properties propSet (of type PropertySpec) and objectSet (of type ObjectSpec).

XML Schema Definition of PropertyFilterSpec Data Object Type

<complexType xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PropertyFilterSpec">
     <complexContent>
          <extension base="vim25:DynamicData">
              <sequence>
                  <element name="propSet" type="vim25:PropertySpec" maxOccurs="unbounded"/>
                  <element name="objectSet" type="vim25:ObjectSpec" maxOccurs="unbounded"/>
              </sequence>
          </extension>
     </complexContent>
</complexType>

Because both elements are defined as a sequence, they must exist in the order listed. To obtain the definitions of propSet and objectSet, you must navigate further into the vSphere API Reference. XML Schema Extract for PropertySpec shows only the relevant parts of the XML Schema definition for PropertySpec. The minOccurs=”0” attribute means that the element does not have to exist. The maxOccurs=”unbounded” attribute means that the element can be populated as an array of any size. (When minOccurs is not set, but maxOccurs is set, the default for minOccurs defaults to 1, meaning one instance is required.)

XML Schema Extract for PropertySpec

<sequence>
     <element name="type" type="xsd:string"/>
     <element name="all" type="xsd:boolean" minOccurs="0"/>
     <element name="pathSet" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
</sequence>

Navigate through the vSphere API Reference to the ObjectSpec definition. ObjectSpec Definition as XML Schema shows the excerpt.

ObjectSpec Definition as XML Schema

...
<sequence>
     <element name="obj" type="vim25:ManagedObjectReference"/>
     <element name="skip" type="xsd:boolean" minOccurs="0"/>
     <element name="selectSet" type="vim25:SelectionSpec" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
...

Extrapolating from the WSDL definitions shown in XML Schema Definition of PropertyFilterSpec Data Object Type, XML Schema Extract for PropertySpec, and ObjectSpec Definition as XML Schema might produce results similar to those shown in CreateFilter Spec Property Entry.

CreateFilter Spec Property Entry

<spec>
     <propSet>
          <type>VirtualMachine</type>
          <all>false</all>
          <pathSet>config.guestFullName</pathSet>
     </propSet>
     <objectSet>
          <obj type=”Folder”>group-v4</obj>
          <skip>true</skip>
     </objectSet>
</spec>

In this example, the <spec> element identifies the spec parameter of the CreateFilter method. The order of the element tags is as defined in the XML Schema for the property (XML Schema Definition of PropertyFilterSpec Data Object Type). The pathSet property defines the full path to the nested data object of interest. In CreateFilter Spec Property Entry, the pathSet property defines the path to the guestFullName property of the target virtual machine. ObjectSpec Definition as XML Schema shows the UML of these nested data objects.

Figure 2. Nested Data Objects

All of these details are available in the vSphere API Reference. By examining the WSDL definition, you can construct the strings needed to submit parameters through the MOB.