VMware vCenter SOAP

Overview

VMware vCenter Server exposes two quite different APIs. Alongside the JSON API used by the VMware vCenter connector, it serves the older vSphere Web Services API over SOAP at /sdk. That SOAP interface is the one the vSphere Client and PowerCLI have always been built on, and it reaches far deeper into the object model: where the JSON API returns a summary of a host, the SOAP PropertyCollector returns whatever property paths you ask for, including hardware inventory, storage device maps and per-VM virtual hardware.

This connector uses the soap.php driver. Authentication posts a Login envelope against the SessionManager to /sdk, carrying the connection username and password inside the XML, and reads the session key out of soapenv.LoginResponse.returnval.key. The driver captures the session cookie vCenter sets on that call and replays it on every subsequent request. Data jobs are all POSTs to /sdk as well. What distinguishes one job from another is the XML Envelope Payload field, which holds the full SOAP envelope to send. Most envelopes are RetrieveProperties calls against the PropertyCollector, naming a managed object type, a list of property paths and the target object. The parsed XML lands in staging tables prefixed vcenter_.

The depth is the reason to use this connector. Fifteen inbound templates pull the properties that drive real estate decisions: host hardware down to CPU model, memory and storage adapters; VM virtual hardware, VMDK file layout, guest OS and VMware Tools state; datastore capacity and free space; cluster configuration; and the guest OS catalog that tells you which operating systems a cluster’s hardware version supports. That last one matters when planning an OS upgrade across a virtual estate, because it tells you where a target OS is not yet supported by the underlying platform.

The connector is registered as bidirectional. In practice it is inbound only: no outbound templates ship, and the outbound job form does not expose an endpoint, a method type or the XML envelope field, so an outbound SOAP call cannot be constructed.

NOTE: Almost every template in this connector is designed to be driven by an enumeration, fetching properties for one object at a time by substituting a managed object identifier into the envelope. None of the shipped templates has that enumeration configured. Read the issues section before enabling the connection.

Connector Properties

Authentication Methods

The connector offers one authentication method, a SOAP login that exchanges a username and password for a vCenter session.

NOTE: The Soap Envelope field holds the login envelope itself, with %user_name% and %user_pass% substituted at run time from the connection’s credential fields. You can edit the envelope, for example to add a locale element, without touching the connector definition.

NOTE: Certificate validation is disabled on both the authentication and the data calls.

Method 1: VMWARE SOAP: username / password – return authorization token (VCENTER_SOAP_673b)

Connect to a SOAP method API with a username / password retrieving value for authorization token

Posts the Login envelope shown in the Soap Envelope field to the Authentication Token End Point (/sdk by default), then extracts the session key from soapenv.LoginResponse.returnval.key. Session continuity on subsequent calls is maintained by the cookie vCenter issues on login, which the driver stores and replays. Use a vCenter account with a read-only role at the vCenter root. The PropertyCollector honours permissions, so an account with partial visibility silently returns a partial inventory.

Connection Configuration Fields (9)

Default value for Soap Envelope:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:vim25">    <soapenv:Header/>    <soapenv:Body>       <urn:Login>          <_this type="SessionManager">SessionManager</_this>          <userName>%user_name%</userName>          <password>%user_pass%</password>       </urn:Login>    </soapenv:Body> </soapenv:Envelope>

Authentication Configuration

Headers sent on the authentication call:

Headers sent on the data calls:

cURL options:

NOTE: The SOAPAction header is fixed at urn:vim25/5.5. vCenter accepts that version for backward compatibility, and it means the calls are made against a long-established schema rather than the newest one your vCenter supports.

Inbound Job Fields Enabled (32)

Inbound jobs expose a smaller form than the JSON connector. The endpoint is effectively fixed at /sdk, and the work is done by the XML Envelope Payload field that carries the SOAP request, the API Return Data Node that picks the element to parse from, and the three enumeration levels that feed managed object identifiers into the envelope.

NOTE: Ignore XML Attributes controls whether XML attributes such as type="HostSystem" are carried into the staging data. It defaults to No, so attributes are retained. The type attribute is often the only thing distinguishing one returnval from another, so leave it off unless the extra columns are causing you problems.

NOTE: No pagination fields are exposed on this connector. Result size is controlled by how narrowly each envelope’s property set and object set are scoped.

Outbound Job Fields Enabled (7)

The outbound form exposes only the job description, enabled flag, data sending method, body encoding, the outbound and return field lists and the job order.

Inbound Job Templates (15)

Fifteen inbound templates ship, twelve of them enabled. Each one posts a specific SOAP envelope to /sdk. They fall into three groups: a service handshake, per-object property retrievals that expect a managed object identifier to be supplied by an enumeration, and folder traversals that walk a datacenter’s object tree. Two of the templates run monthly because their data changes rarely, and the rest run daily.

Job Template Configuration

Settings Common to All Fifteen Templates

Settings That Vary by Template

Settings That Vary by Template (continued)

Job Parameters and Enumeration

GET vCenter Service Content

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:vim25">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:RetrieveServiceContent>
         <_this>ServiceInstance</_this>
      </urn:RetrieveServiceContent>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Cluster Info

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:vim25">
 <soapenv:Body>
      <RetrieveProperties>
         <_this type="PropertyCollector">propertyCollector</_this>
        <specSet>
            <propSet>
               <type>ClusterComputeResource</type>
                <pathSet>host</pathSet>
                <pathSet>configuration</pathSet>
                <pathSet>summary</pathSet>
                <pathSet>name</pathSet>
            </propSet>
            <objectSet>
               <obj type="ClusterComputeResource">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Host Info

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
      <RetrieveProperties xmlns="urn:vim25">
         <_this type="PropertyCollector">propertyCollector</_this>
         <specSet>
            <propSet>
               <type>HostSystem</type>
               <pathSet>name</pathSet>
               <pathSet>runtime.connectionState</pathSet>
               <pathSet>runtime.powerState</pathSet>
               <pathSet>hardware</pathSet>
               <pathSet>summary.config.product</pathSet>
               <pathSet>config.storageDevice.scsiLun</pathSet>
               <pathSet>config.storageDevice.multipathInfo</pathSet>
               <pathSet>config.network.vnic</pathSet>
            </propSet>
            <objectSet>
               <obj type="HostSystem">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter VM Info

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <RetrieveProperties xmlns="urn:vim25">
         <_this type="PropertyCollector">propertyCollector</_this>
         <specSet>
            <propSet>
               <type>VirtualMachine</type>
               <pathSet>resourcePool</pathSet>
               <pathSet>config.cpuAllocation</pathSet>
               <pathSet>config.memoryAllocation</pathSet>
               <pathSet>config.hardware</pathSet>
               <pathSet>layoutEx.file</pathSet>
               <pathSet>guest</pathSet>
               <pathSet>summary</pathSet>
               <pathSet>network</pathSet>
            </propSet>
            <objectSet>
               <obj type="VirtualMachine">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Resource Pool Info

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <RetrieveProperties xmlns="urn:vim25">
         <_this type="PropertyCollector">propertyCollector</_this>
         <specSet>
            <propSet>
               <type>ResourcePool</type>
               <pathSet>name</pathSet>
               <pathSet>parent</pathSet>
               <pathSet>owner</pathSet>
               <pathSet>resourcePool</pathSet>
               <pathSet>vm</pathSet>
               <pathSet>config.cpuAllocation</pathSet>
               <pathSet>config.memoryAllocation</pathSet>
            </propSet>
            <objectSet>
               <obj type="ResourcePool">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter Info

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
        <RetrieveProperties xmlns="urn:vim25">
			 <_this type="PropertyCollector">propertyCollector</_this>
			 <specSet>
				 <propSet>
					 <type>Datacenter</type>
					 <pathSet>hostFolder</pathSet>
					 <pathSet>datastore</pathSet>
					 <pathSet>datastoreFolder</pathSet>
					 <pathSet>network</pathSet>
					 <pathSet>networkFolder</pathSet>
					 <pathSet>vmFolder</pathSet>
				 </propSet>
				 <objectSet>
					 <obj type="Datacenter">%enum_id_1%</obj>
				 </objectSet>
			 </specSet>
		 </RetrieveProperties>
	 </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter VM Info

Additional staging fields:

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
	   <RetrievePropertiesEx xmlns="urn:vim25">
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>VirtualMachine</type>
				   <pathSet>name</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Folder">%enum_id_1%</obj>
				   <skip>false</skip>
				   <selectSet xsi:type="TraversalSpec">
					   <name>folderTraversalSpec</name>
					   <type>Folder</type>
					   <path>childEntity</path>
					   <skip>false</skip>
				   </selectSet>
			   </objectSet>
		   </specSet>
		   <options/>
	   </RetrievePropertiesEx>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter Host Info

Additional staging fields:

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:vim25" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
	   <RetrieveProperties>
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>HostSystem</type>
				   <pathSet>name</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Folder">%enum_id_1%</obj>
				   <skip>false</skip>
				   <selectSet xsi:type="TraversalSpec">
					   <name>folderTraversal</name>
					   <type>Folder</type>
					   <path>childEntity</path>
					   <skip>false</skip>
					   <selectSet>
						   <name>folderTraversal</name>
					   </selectSet>
					   <selectSet xsi:type="TraversalSpec">
						   <name>dcToHf</name>
						   <type>Datacenter</type>
						   <path>hostFolder</path>
						   <skip>false</skip>
					   </selectSet>
					   <selectSet xsi:type="TraversalSpec">
						   <name>crToH</name>
						   <type>ComputeResource</type>
						   <path>host</path>
						   <skip>false</skip>
					   </selectSet>
				   </selectSet>
			   </objectSet>
		   </specSet>
	   </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter VM Folder

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
	   <RetrieveProperties xmlns="urn:vim25">
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>Datacenter</type>
				   <pathSet>vmFolder</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Datacenter">%enum_id_1%</obj>
			   </objectSet>
		   </specSet>
	   </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter Host Folder

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
	   <RetrieveProperties xmlns="urn:vim25">
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>Datacenter</type>
				   <pathSet>hostFolder</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Datacenter">%enum_id_1%</obj>
			   </objectSet>
		   </specSet>
	   </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter Datastore Folder

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
	   <RetrieveProperties xmlns="urn:vim25">
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>Datacenter</type>
				   <pathSet>datastoreFolder</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Datacenter">%enum_id_1%</obj>
			   </objectSet>
		   </specSet>
	   </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datacenter Datastore Info

Additional staging fields:

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:vim25" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
	   <RetrieveProperties>
		   <_this type="PropertyCollector">propertyCollector</_this>
		   <specSet>
			   <propSet>
				   <type>Datastore</type>
				   <pathSet>name</pathSet>
			   </propSet>
			   <objectSet>
				   <obj type="Folder">%enum_id_1%</obj>
				   <skip>false</skip>
				   <selectSet xsi:type="TraversalSpec">
					   <name>folderTraversal</name>
					   <type>Folder</type>
					   <path>childEntity</path>
					   <skip>false</skip>
					   <selectSet>
						   <name>folderTraversal</name>
					   </selectSet>
					   <selectSet xsi:type="TraversalSpec">
						   <name>spToDs</name>
						   <type>StoragePod</type>
						   <path>childEntity</path>
						   <skip>false</skip>
					   </selectSet>
				   </selectSet>
			   </objectSet>
		   </specSet>
	   </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Datastore Info

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
      <RetrieveProperties xmlns="urn:vim25">
         <_this type="PropertyCollector">propertyCollector</_this>
         <specSet>
            <propSet>
               <type>Datastore</type>
               <pathSet>name</pathSet>
               <pathSet>summary.type</pathSet>
               <pathSet>summary.url</pathSet>
               <pathSet>summary.capacity</pathSet>
               <pathSet>summary.freeSpace</pathSet>
               <pathSet>summary.accessible</pathSet>
               <pathSet>info</pathSet>
               <pathSet>host</pathSet>
            </propSet>
            <objectSet>
               <obj type="Datastore">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Compute Resource Info

Enumeration 1 fields:

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <RetrieveProperties xmlns="urn:vim25">
         <_this type="PropertyCollector">propertyCollector</_this>
         <specSet>
            <propSet>
               <type>ClusterComputeResource</type>
               <pathSet>name</pathSet>
               <pathSet>environmentBrowser</pathSet>
            </propSet>
            <objectSet>
               <obj type="ClusterComputeResource">%enum_id_1%</obj>
            </objectSet>
         </specSet>
      </RetrieveProperties>
   </soapenv:Body>
</soapenv:Envelope>

GET vCenter Guest OS Catalog

XML Envelope Payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <QueryConfigOption xmlns="urn:vim25">
         <_this type="EnvironmentBrowser">%enum_id_1%</_this>
      </QueryConfigOption>
   </soapenv:Body>
</soapenv:Envelope>

NOTE: The folder templates and the info templates are two halves of a chain. GET vCenter Datacenter VM Folder, Host Folder and Datastore Folder produce folder identifiers keyed by datacenter, and GET vCenter Datacenter VM Info, Host Info and Datastore Info consume them through an enumeration that reads both the value and the key. The three folder jobs ship disabled while their three consumers ship enabled.

NOTE: The per-object templates (cluster, host, VM, resource pool, datacenter, datastore) each fetch one object per call. On an estate with several thousand virtual machines, GET vCenter VM Info is several thousand SOAP calls per run once enumeration is configured. Plan the schedule and the Pause Enumeration setting accordingly.

Outbound Job Templates (0)

No outbound templates ship with this connector, and the outbound job form does not expose an API End Point, a Method Type or the XML Envelope Payload field, so an outbound SOAP call cannot be built here. Treat the connector as inbound only.