Retrieval of VM managers

You use the GET operation on the api/sam/vmmanagers element to request information about VM managers that are defined in your infrastructure. The REST API returns more information than is visible on the user interface. It returns information about VM managers that are managed both in central and distributed mode, VM managers that were inactive for more than 90 days as well as those that were removed. It also returns information from virtualization technologies that do not require defining connection to the VM manager such as Xen or KVM without RHEV-M. The scope of VM managers from which data is collected depends on which VM Manager Tools are installed on computers that belong to the computer group to which you are assigned.

To retrieve information about VM managers, you must have the Manage VM Managers and Servers permission.

Table 1. Operation descriptions

The table consists of two columns and 15 rows. For the eleventh row there are two levels.
Operation details Description
Operation GET /api/sam/vmmanagers
Purpose Returns a list of VM managers.
HTTP method GET
Resource URI https://server_host_name:port_number/api/sam/vmmanagers?token=token
Request Content-Type application/json
Response Content-Type application/json
Normal HTTP response codes
  • 200 – OK
Error HTTP response codes
  • 400 – "Bad Request" if a query parameter contains errors or is missing
  • 401 – "Unauthorized" if the user does not have the Manage VM Managers and Servers permission
  • 403 – "Forbidden" if the computer where the central VM Manager Tool is installed does not belong to the computer group that the user is assigned
  • 500 – "Internal Server Error" if no VM Manager Tool is defined in the BigFix Inventory database.

Message body includes an error message with details.

Response attributes

Table 2. Response attributes and their possible values
Attribute Possible values
deleted Indicates whether the VM manager was removed from BigFix Inventory.
lastmodified The date and time when the VM manager was last modified.
login User name that is used to access the VM manager.
protocol Communication protocol used by the VM manager. The attribute is applicable only for Hyper-V.
  • 0 - WinRM
  • 1 - PowerShell
  • null - the VM manager is not Hyper-V
sharedcredentials Indicates whether the VM manager shares credentials with other hosts in the same cluster. The attribute is applicable only for Hyper-V.
status Status of the VM manager.
  • -1 - Invalid credentials - suspended
  • 0 - Pending
  • 1 - OK
  • 2 - Connection failed
  • 3 - Invalid credentials - attempting
  • 6 - Duplicated address
  • 7 - Hard timeout - suspended
  • 8 - OK - duplicated UUIDs discarded
  • 9 - No VM Manager Data
  • 98 - Inactive
  • 99 - Unknown problem
For more information about each status, see: VM manager statuses.
type Type of the VM manager.
  • 1 - Hyper-V
  • 2 - VMware vSphere or VMware ESX
  • 3 - RHEV-M
  • 9.2.12 4 - XenServer or Citrix XenServer
  • 99 - Other. The value is used for VM managers for which data is collected by using the Run Capacity Scan on Virtualization Hosts task, for example Xen and KVM without RHEV-M.
url Web address of the VM manager.
vmmanagerid ID of the VM manager.
vmmanagertoolid ID of the VM Manager Tool that collects information from the particular VM manager.

Example HTTP conversation

Request
GET http://localhost:9081/api/sam/vmmanagers
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Response body (JSON)

[{
    "vmmanagerid":1,
    "protocol":null,
    "deleted":false,
    "vmmanagertoolid":1,
    "sharecredentials":false,
    "lastmodified":"2016-06-12 09:06:51.723",
    "login":"admin@internal",
    "type":3,
    "url":"https:\/\/9.156.44.146:8443\/api",
    "status":98
}]