Filtering Extensions

In your extension definition, you can use filtering metadata to control when the extension appears in the vSphere Client GUI.

You can filter extensions based on the selected object type, on the value of any property associated with the selected object, or on the user’s privilege level. You set the filter type and the specific filter values by using the appropriate XML elements inside the <metadata> element of your extension definition.

Filtering Based on Selected Object Type

You can filter your extension to appear only when the user selects one or more specific types of vSphere objects. You specify the types of objects for which the extension is valid by creating an <objectType> element in the <metadata> element in the extension definition. The extension appears only when the user selects an object whose type matches the value of the <objectType> element.

You can use any vSphere or custom object type name as the value for the <objectType> element. To specify multiple object types, include two or more object type names in the <objectType> element, separated by commas. You can also use the * symbol to specify all object types.

Extension Filtered by Entity Type

The following example filters the extension action to appear only when the user has selected a virtual machine object.

<extension id="com.vmware.samples.actions.vmActionSet">
    <extendedPoint>vise.actions.sets</extendedPoint>
    <object>
      <actions>
        <com.vmware.actionsfw.ActionSpec>
          <uid>com.vmware.samples.actions.myVmAction1</uid>
          <label>#{action1.label}</label>
          <command className="com.vmware.samples.actions.VmActionCommand"/>
        </com.vmware.actionsfw.ActionSpec>
      </actions>
    </object>
    <metadata>
        <!-- This filters the action to be visible only on VMs -->
      <objectType>VirtualMachine</objectType>
    </metadata>
</extension>

Filtering Based on the Value of a Property of the Selected Object

You can filter your extension to appear or not depending on the value of a property of the selected object. You must use the property value filter together with the object type filter.

You create the property value filter by describing one or more property value comparisons to be made on the selected object by using the <propertyConditions> element. You include the <propertyConditions> element in the <metadata> element in the extension definition. You can define a single comparison, or define multiple comparisons and conjoin those comparisons together.

In the <propertyConditions> element, you must describe a data object of type com.vmware.data.query.CompositeConstraint using MXML syntax. Using the CompositeConstraint data object, you specify the names of the object properties used in the filter, the desired value for each object property, and the comparison operator. You can also specify a conjoiner if your CompositeConstraint data object has multiple comparisons.

In the CompositeConstraint data object, you describe each property value comparison using the <nestedConstraints> element. The <nestedConstraints> element contains an array of data objects of type com.vmware.data.query.PropertyConstraint. Each PropertyConstraint data object represents one comparison between a given object property and a value you specify.

When you create a PropertyConstraint data object, you specify the object property to compare by using the <propertyName> element, the value to compare against using the <comparableValue> element, and the comparison operator using the <comparator> element.

The value of the <propertyName> element must match the name of the object property to compare. You can set the value of the <comparableValue> element depending on the type of property you are comparing, but the value must be a primitive type. You can use a string value, an integer value, or a Boolean value of true or false in the <comparableValue> element.

You use the <comparator> element to choose how the property is compared against the value you specify in the filter. You can use values of EQUALS, NOT_EQUALS, GREATER, SMALLER, CONTAINS, EQUALS_ANY_OF or CONTAINS_ANY_OF. If you use the CONTAINS operator, you must provide an array of values. If you use the operators EQUALS_ANY_OF or CONTAINS_ANY_OF, you must provide a string containing multiple values in the <comparableValue> element, each separated by a comma.

If your CompositeConstraint data object defines multiple comparisons, you can choose how those comparisons are conjoined by using the <conjoiner> element. You can use a value of AND or ORin the <conjoiner> element.

Example Property Value Filter

The following example filters an action extension only when the value of the isRootFolder property is true and the selected object contains child objects that are virtual machines.

<extension id="com.vmware.samples.actions.vmActionSet">
   <extendedPoint>vise.actions.sets</extendedPoint>
   <object>
      <actions>
         <com.vmware.actionsfw.ActionSpec>
            <uid>com.vmware.samples.actions.myVmAction1</uid>
            <label>#{action1.label}</label>
            <command className="com.vmware.samples.actions.VmActionCommand"/>
         </com.vmware.actionsfw.ActionSpec>
      </actions>
   </object>
   <metadata>
      <objectType>Folder</objectType>
      <propertyConditions>
         <com.vmware.data.query.CompositeConstraint>
            <nestedConstraints>
               <com.vmware.data.query.PropertyConstraint>
                  <propertyName>isRootFolder</propertyName>
                  <comparator>EQUALS</comparator>
                  <comparableValue>
                     <String>true</String>
                  </comparableValue>
               </com.vmware.data.query.PropertyConstraint>
               <com.vmware.data.query.PropertyConstraint>
                  <propertyName>childType</propertyName>
                  <comparator>CONTAINS</comparator>
                  <comparableValue>
                     <String>VirtualMachine</String>
                  </comparableValue>
               </com.vmware.data.query.PropertyConstraint>
            </nestedConstraints>
            <conjoiner>AND</conjoiner>
         </com.vmware.data.query.CompositeConstraint>
      </propertyConditions>
   </metadata>
</extension>

Filtering Based on User Privilege Level

You can filter your extension to appear only for users that have specific privileges. You can base your filter on global privilege settings in the vSphere Client, such as settings or licenses. For example, you can use a filter to make your extension available only to users that have global privileges to change settings.

You can also filter your extension based on privileges related to specific types of vSphere objects. For example, you can use a filter to make your extension available only to users who have privileges to create or delete datastore objects.

You specify the privilege for which the object is valid by creating a <privilege> element inside the <metadata> element in the extension definition. The extension appears only for users whose privileges include the value specified by the <privilege> element. You can specify multiple privilege values in the <privilege> element, separated by commas. If you specify multiple privileges, the user must have all specified privilege values for the extension to appear.

Limitations on Filtering Based on User Privilege Level

Filtering has no effect on nodespecs and shortcut items. To avoid impacting the load time of the object navigator, home screen, and main menu, the vSphere Client does not check permissions for nodespecs and shortcut items.

The vSphere Client shows plug-in views only if the user has the appropriate privilege. If not, the user interface displays a message informing the user of the lack of privilege.

Extension Filtered by User Privileges

The following example filters the extension to appear only when the user privileges include Global.Licenses.

<extension id="vsphere.core.hosts.sampleMonitorView">
  <extendedPoint>vsphere.core.hosts.monitorViews</extendedPoint>
  <object>
    <name>Sample Monitor View Title</name>
    <componentClass className="com.vmware.vsphere.client.sampleplugin.SampleObjectView"/>
  </object>
  <metadata>
    <privilege>Global.Licenses</privilege>
  </metadata>
</extension>