Retrieve or Modify ProductSection Elements

ProductSection elements allow you to pass runtime information to vApps and virtual machines. The key=value pairs in this section are made available in the OVF Environment of a powered-on vApp or virtual machine.

A vApp or virtual machine can get runtime information from its ovf:Environment element. This read-only element is populated with information from a ProductSection element when the vApp or virtual machine is powered on. A Vm can use VMware Tools to read these values from its ovf:Environment. A Vm can also read the values by mounting a special media object. To make a key=value pair available in the ovf:Environment, add it to the appropriate ProductSection of a vApp template or powered-off vApp or virtual machine.

Note:

All ProductSection elements in a vApp template, vApp, or virtual machine are returned as members of a ProductSectionList. You cannot retrieve or update an individual ProductSection. You must retrieve and modify the ProductSectionList to update the individual ProductSection elements it contains.

Prerequisites

This operation requires the rights included in the predefined vApp Author role or an equivalent set of rights.

Procedure

  1. Retrieve the ProductSectionList from the vApp or virtual machine.
    Use a request like this one, which targets a vApp. 
    GET https://vcloud.example.com/api/vApp/vapp-123/productSections
    The response is a ProductSectionList element, which contains all the ProductSection elements in the vApp, along with a Link element that contains the rel="edit" URL to use when updating the ProductSectionList. If the vApp contains no ProductSection elements, the response contains only the Link element.
  2. Modify the retrieved ProductSectionList.
    You can modify existing ProductSection elements, create new ones, or both. ProductSection has no required contents. Unlike updates to other sections, updates to a ProductSection merge new and existing values, subject to the following rules:
    • Property elements that are present in the existing ProductSection but not in the update are removed.
    • Property elements that are present in the update but not in the in the existing ProductSection are added to the ProductSection if they have a corresponding Value element.
    • If a Property element that is present in the existing ProductSection has different attributes, qualifiers, or other details in the update, the Property in the update replaces the existing one.
    • If a Property element that is present in the existing ProductSection has no Value in the update, the existing Property and Value remain unchanged.
  3. Update the section with your modifications.
    Find the Link element in the ProductSectionList where rel="edit". Make a PUT request to the URL in that link's href attribute value, and supply the modified ProductSectionList as the request body.
    The response to this request is a Task element that tracks the update operation. When the task is complete, the section is updated.

Results

The modified section replaces the contents of the original section, subject to the rules listed in Step 2.

Example: Update a ProductSection in a vApp

This request creates or updates a ProductSectionList that contains a single ProductSection. The ProductSection sets three properties. The response is a Task.

Request: 
PUT https://vcloud.example.com/api/vApp/vapp-123/productSections
Content-Type: application/vnd.vmware.vcloud.productSections+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ProductSectionList
   xmlns="http://www.vmware.com/vcloud/v1.5"
   xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1">
   <ovf:ProductSection
      required="true">
      <ovf:Info>Information about the installed software</ovf:Info>
      <ovf:Property
         ovf:type="string"
         ovf:key="CRM_Database_Host"
         ovf:value="CRM.example.com">
         <ovf:Label>CRM Database Host</ovf:Label>
      </ovf:Property>
      <ovf:Property
         ovf:type="string"
         ovf:key="CRM_Database_Username"
         ovf:value="dbuser">
         <ovf:Label>CRM Database Usernname</ovf:Label>
      </ovf:Property>
      <ovf:Property
         ovf:type="string"
         ovf:key="CRM_Password"
         ovf:value="Pa55w0rd">
         <ovf:Label>CRM Database User Password</ovf:Label>
      </ovf:Property>
   </ovf:ProductSection>
</ProductSectionList>
Response: 
202 Accepted
Content-Type: application/vnd.vmware.vcloud.task+xml
...
<Task ... operation="Updating Virtual Application ..." ...>
...
</Task>

After the vApp is powered on, a virtual machine can retrieve the ovf:Environment document in the following ways:

  • It can use the default OVF iso transport type. This makes the environment document available as a file named ovf-env.xml on an ISO image that is mounted on the first available CD-ROM device on the virtual machine. You can use any convenient mechanism to read this file. 
    [root@example-vm-RHEL ~] cat /media/cdrom/ovf-env.xml
<?xml version="1.0" encoding="UTF-8"?>
<Environment ...>
   ...
   <PropertySection>
      <Property
         oe:key="CRM_Database_Host"
         oe:value="CRM.example.com" />
      <Property
         oe:key="CRM_Database_Username"
         oe:value="dbuser" />
      <Property
         oe:key="CRM_Password"
         oe:value="Pa55w0rd" />
    </PropertySection>
   ...
</Environment>
  • If the virtual machine has VMware Tools installed, it can use the vmtoolsd program, as shown here. 
    [root@example-vm-RHEL ~] /usr/sbin/vmtoolsd --cmd 'info-get guestinfo.ovfEnv'
<?xml version="1.0" encoding="UTF-8"?>
<Environment ...>
   ...
   <PropertySection>
      <Property
         oe:key="CRM_Database_Host"
         oe:value="CRM.example.com" />
      <Property
         oe:key="CRM_Database_Username"
         oe:value="dbuser" />
      <Property
         oe:key="CRM_Password"
         oe:value="Pa55w0rd" />
    </PropertySection>
   ...
</Environment>

    On Windows, the vmtoolsd executable file is typically installed in C:\Program Files\VMware\VMware Tools\vmtoolsd.exe