Adding and updating VM managers

You use the PUT operation on the api/sam/vmmanagers element to add or update VM managers.

Permissions

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

Resource URL

https://server_url:server_port/api/sam/vmmanagers

Resource information

Table 1. Resource information
Operation details	Description
Purpose	Adds a new VM manager or changes an existing one.
HTTP method	`PUT`
Resource URI	https://`server_url`:`server_port`/api/sam/vmmanagers
Request `Content-Type`	`application/json`
Request headers	`Accept-Language` (optional) Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language. Values: `en-US` (only English is supported) `Token` Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests. Values: an alphanumeric string that is generated in License Metric Tool
Response `Content-Type`	`application/json`
Response headers	`Content-Type` Use: Specifies the content type of the response. Values: `application/json` `Content-Language` Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language. Values: en-US, …
Normal HTTP response codes	`200 - OK`
Error HTTP response codes	`207 – "Multi-Status"` if at least one of the actions failed due to an incorrect value of a parameter. For example, if you added two VM managers and updated one VM manager, and any of the actions failed, the 207 response is returned with information about the status and details of each action. `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 no VM Manager Tool is defined in the License Metric Tool database. The code might also indicate an unknown problem that requires contacting IBM support.

Request attributes

Table 2. Request attributes
Attribute	Description
`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 and Azure Stack HCI. 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 and Azure Stack HCI. `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 or Azure Stack HCI 2 - VMware vSphere or VMware ESX 3 - RHV-M or Oracle Linux Virtualization Manager 4 - Citrix Hypervisor (formerly XenServer) 6 - Nutanix
`url`	Web address of the VM manager. To add a VM manager, specify its full URL. The default URL differs depending on the virtualization type. Red Hat OpenShift: `https://{manager-address}:6443` Citrix Hypervisor (formerly XenServer): `https://{manager-address}` Hyper-V or Azure Stack HCI: `https://{manager-address}:5986/wsman` In case of Azure Stack HCI, provide a connection to a host in the cluster. Then, share credentials to connect to other hosts. If it is not possible, configure a connection to each host in the cluster separately. Nutanix: `https://{manager-address}:9440/PrismGateway/services/rest/v2.0` Oracle Linux Virtualization Manager: `https://{manager-address}/ovirt-engine/api` RHV-M: `https://{manager-address}/ovirt-engine/api` vCenter: `https://{manager-address}/sdk/vimService.wsdl`
`vmmanagerid`	ID of the VM manager that you want to change. To obtain the ID, use REST API for the retrieval of VM managers.
`vmmanagertooltype`	VM Manager Tool deployment type. 1 - Central 2 - Local For more information, see: VM Manager Tool deployment types and flow of data.
`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:

login
password
url
type

Request

PUT https://server_url:server_port/api/sam/vmmanagers

Request header

Accept: application/json
Accept-Language: en-US
Token: <token>

Request body

[{
    "login":"user1",
    "password":"<password_1>",
    "url":"<URL_1>",
    "type":1
}]

Response header

Example HTTP conversation - adding a VM manager that failed

Request

PUT https://server_url:server_port/api/sam/vmmanagers

Request header

Accept: application/json
Accept-Language: en-US
Token: <token>

Request body

[{
    "login":"user1",
    "password":"<password_1>",
    "url":"<URL_1>",
    "type":1
}]

Response header

Response body

{
	"status": 
	[
		{
			"description":
			{
				"description":
				{
					"type": 1,
					"url": "<URL_1>"
				},
				"type": "VMMAN"
			},
			"id": 1,
			"actions":
			[
				{
					"type": "ADD",
                                 "error": "Empty or not valid property: Login.",
					"status": "FAILURE"
				}
			]
		}
	]
}

Example HTTP conversation - changing a VM manager

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

vmmanagerid
login
password
url
type

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

Request

PUT https://server_url:server_port/api/sam/vmmanagers

Request header

Accept: application/json
Accept-Language: en-US
Token: <token>

Request body

[{
    "vmmanagerid":1,
    "login":"user1",
    "password":"<password>",
    "url":"<URL>",
    "type":3
}]

Response

200 OK