Adding and updating VM managers

You use the PUT operation on the api/sam/vmmanagers element to add or update VM managers. For versions below 11.0.7, you can perform these actions only for VM managers that are managed in central mode. Since version 11.0.8, you can perform add and update actions for all VM Managers.

To add or update VM managers, the following requirements must be met:

You must have the Manage VM Managers and Servers permission
The computer group to which you are assigned must contain the computer on which the VM Manager tool is installed

Table 1. Operation descriptions
Operation details	Description
Operation	`PUT api/sam/vmmanagers`
Purpose	Adds a new VM manager or changes an existing one.
HTTP method	`PUT`
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. The code might also indicate an unknown problem that requires contacting BigFix support.

Note: The backslash character is a reserved character and can not be used in JSON. It must be properly escaped to be used in strings. Replace Backslash with \\. It applies to all fields in the API.

Request attributes

Table 2. Request attributes
Attribute	Description
`vmmanagertoolid`	The ID of VM Manager Tool where VM Manager configuration will be updated. The ID can be retrieved using VM Manager Tools REST API.
`vmmanagers`	It includes a list of VM Manager configurations for the specified VM Manager Tool. Each item defines one VM Manager connection.
`login`	User name that is used to access the VM manager.
`password`	Password that is used to access the VM manager. The password is encrypted after it is sent.
`protocol`	Communication protocol used by the VM manager. The attribute is applicable only for Hyper-V. 0 - WinRM 1 - PowerShell
`sharecredentials`	Indicates whether the VM manager shares credentials with other hosts in the same cluster. The attribute is applicable only for Hyper-V. `true` - the VM manager shares the credentials and it is not necessary to specify them `false` - the VM manager does not share the credentials
`type`	Type of the VM manager. 1 - Hyper-V 2 - vCenter 3 - RHV-M 4 - Citrix Hypervisor (formerly XenServer)
`url`	Web address of the VM manager. You can specify a full URL, a host name, or an IP address. The default URL differs depending on the virtualization type.
`vmmanagerid`	ID of the VM manager that you want to change. To obtain the ID, use REST API for the retrieval of VM managers.
`vmmanagertoolid`	ID of the VM Manager tool that collects data from the VM manager that you want to change. To obtain the ID, use REST API for the retrieval of VM managers.

Example HTTP conversation - adding a VM manager

To add a new VM manager, provide the following attributes:

vmmanagers
vmmanagertoolid
login
password
url
type

Request

PUT http://localhost:9081/api/sam/vmmanagers
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
{
  "vmmanagertoolid": 1,
  "vmmanagers": [
    {
        "login":"user1",
        "password":"vZaW1Ve6",
        "url":"192.0.2.24",
        "type":2
    },
    {
        "login":"user2",
        "password":"aFoG3ccG",
        "url":"10.190.2.24",
        "type":3
    }
  ]
}

Note: One or more VM Managers can be added in 1 request for 1 specified VM Manager Tool.

PUT http://localhost:9081/api/sam/vmmanagers
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
[
    {
        "login":"user1",
        "password":"vZaW1Ve6",
        "url":"192.0.2.24",
        "type":2
    }
]

Response

200 OK

Example HTTP conversation - changing a VM manager

To change an existing VM manager, provide the following attributes:

vmmanagers
vmmanagertoolid
login
password
url
type
vmmanagerid
vmmanagertoolid

Important: All attributes must be provided in the request regardless of how many of the attributes you want to change.

Request

PUT http://localhost:9081/api/sam/vmmanagers
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
{
  "vmmanagertoolid": 1,
  "vmmanagers": [
    {
        "login":"user1",
        "password":"vZaW1Ve6",
        "url":"192.0.2.24",
        "type":2
    },
    {
        "login":"user2",
        "password":"aFoG3ccG",
        "url":"10.190.2.24",
        "type":3
    }
  ]
}

Note: One or more VM Managers can be updated in 1 request for 1 specified VM Manager Tool.

PUT http://localhost:9081/api/sam/vmmanagers
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
[
    {
        "vmmanagerid":1,
        "vmmanagertoolid":1,
        "login":"user1",
        "password":"vZaW1Ve6",
        "url":"192.0.2.24",
        "type":3
    }
]

Response

200 OK