POST /manageRequest

Use the POST method to manage devices. The response header includes a URI that is associated with a job that indicates that a task was started.

Authentication

Authentication with user name and password is required.

Request URL

POST https://<management_server_IP>/manageRequest

Query parameters

Parameters Required / Optional Description
discovery=<Boolean> Optional Indicates whether to discover endpoints as part of this management request. This can be one of the following values.
  • true. Discovers endpoints as part of this request.

  • false. (default) Does not discover endpoints as part of this request. The devices must have been previously discovered using the POST /discoverRequest method.

The following example discovers and manages endpoints.
POST https://192.0.2.0/manageRequest?discovery=true
The following example manages endpoints have endpoints that have been discovered.
POST https://192.0.2.0/manageRequest

Request body

Table 1. Discover and manage a device.
Attributes Required / Optional Type Description
enableHttps Optional Boolean (Rack switches running ENOS only) Indicates whether to enable HTTPS on the switch. This can be one of the following values.
  • true. (default) Enable HTTPS.

  • false. Do not enable HTTPS.

enablePassword Optional String (Rack switches running ENOS only) "Enable" password that is used to enter Privileged Exec Mode on the switch
forceManage Optional Boolean Indicates whether to force management of the device. This can be one of the following values.
  • true. Force management.

  • false. Do not force management.

Note: Use this force-management option only if you previously attempted to manage the device and management was not successful due to one of the following error conditions.
  • If the managing XClarity Administrator failed and cannot be recovered.

    Note: If the replacement XClarity Administrator instance uses the same IP address as the failed XClarity Administrator, you can manage the device again using the RECOVERY_ID account and password (if applicable) and the Force management option.
  • If the managing XClarity Administrator was taken down before the devices were unmanaged.

  • If the devices were not unmanaged successfully.

Attention: Devices can be managed by only one XClarity Administrator instance at a time. Management by multiple XClarity Administrator instances is not supported. If a device is managed by one XClarity Administrator, and you want to manage it with another XClarity Administrator, you must first unmanage the device from the original XClarity Administrator, and then manage it with the new XClarity Administrator.
ipAddresses Required Array of strings List of device IP addresses or fully-qualified domain names
newPassword Optional String (Chassis and servers only) New password to be used for managed authentication
password Required String Current password to access the device
recoveryPassword Optional String Recovery password to be used for the device
replaceNtpConfiguration Optional Boolean (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
  • true. (default) Replace the NTP and time zone settings.

  • false. Do not replace the NTP and time zone settings.

securityDescriptor Required Object Information about the authentication enablement and support the associated stored credentials for a managed device
  managedAuthSupported Required for ThinkServer devices Boolean Indicates whether the device supports the ability to choose whether managed authentication is to be used. This can be one of the following values.
  • true. This device supports the ability to choose managed authentication.

  • false. This device does not support the ability to choose managed authentication.

  managedAuthEnabled Required for devices other than ThinkServer Boolean Indicates whether the device uses managed authentication. This can be one of the following values.
  • true. The device uses managed authentication.

  • false. The device uses local authentication.

  roleGroups Optional Array of strings List of role groups that are permitted to view and manage the device. To get a list of available role groups, use GET /roleGroups.

You can specify only role groups to which the current user belongs.

If you do not specify the roleGroups attribute, the default roles groups are assigned. You can obtain the list of default role group using GET /resourceAccessControl.

If you specify the roleGroups attributes= with an empty or null value, role groups are not assigned.

Note: If you add devices to a managed chassis, the new devices will belong to the same role groups as the chassis.
  storedCredentials Required if managedAuthEnabled is set to true Object Information about the stored credential that is associated with this device, if applicable
Note: RackSwitch devices support only stored credentials for authenticating to the switches. Manual user credentials are not supported.
    description Optional String Description of the stored credential
    id Required String ID of the stored credential
    userName Optional String Name of the stored credential
type Required String Type of device to be managed. This can be one of the following values.
  • Chassis
  • Edge Server. ThinkSystem SE server
  • Lenovo ThinkServer
  • Lenovo Storage
  • Rackswitch
  • Rack-Tower Server. Converged, NeXtScale, System x or ThinkSystem SD, SR, or ST server
username Required String User ID to be used to access the device
Note: RackSwitch devices support only stored credentials (using the storedCredentials attribute) for authenticating to the switches. Manual user credentials using the username and password attributes are not supported and must be empty or null..
Table 2. Manage a discovered device.
Attributes Required / Optional Type Description
displayName Optional String (Rack switches only) Name of the device
enableHttps Optional Boolean (Rack switches running ENOS only) Indicates whether to enable HTTPS on the switch. This can be one of the following values.
  • true. (default) Enable HTTPS.

  • false. Do not enable HTTPS.

enclosureFormFactor Optional String (IMM, IMM2, and XCC only) Form factor of the device. This can be one of the following values.
  • rack-tower

  • dense-computing

enablePassword Optional String (Rack switches running ENOS only) "Enable" password that is used to enter Privileged Exec Mode on the switch
forceManage Optional Boolean Indicates whether to force management of the device. This can be one of the following values.
  • true. Force management.

  • false. Do not force management.

Note: Use this force-management option only if you previously attempted to manage the device and management was not successful due to one of the following error conditions.
  • If the managing XClarity Administrator failed and cannot be recovered.

    Note: If the replacement XClarity Administrator instance uses the same IP address as the failed XClarity Administrator, you can manage the device again using the RECOVERY_ID account and password (if applicable) and the Force management option.
  • If the managing XClarity Administrator was taken down before the devices were unmanaged.

  • If the devices were not unmanaged successfully.

Attention: Devices can be managed by only one XClarity Administrator instance at a time. Management by multiple XClarity Administrator instances is not supported. If a device is managed by one XClarity Administrator, and you want to manage it with another XClarity Administrator, you must first unmanage the device from the original XClarity Administrator, and then manage it with the new XClarity Administrator.
fruNumber Optional String (Rack switches only) FRU number
hostname Optional String (Rack switches only) hostname of the device
ipAddresses Required Array of strings List of device IP addresses or fully-qualified domain names
ipv4Addresses Optional Array of strings (Rack switches only) List of IPv4 IP addresses
ipv6Addresses Optional Array of strings (Rack switches only) List of IPv6 IP addresses
managementProcessor Required for ThinkSystem devices; otherwise, optional String (Chassis and servers only) Type of management controller. This can be one of the following values.
  • integrated-management-module

  • integrated-management-module2

  • lenovo-xclarity-controller

  • chassis-management-module

managementPorts Optional for switches; otherwise, required Array List of device management ports
  enabled Required Boolean Indicates whether the port enabled. This can be one of the following values.
  • true. The port is enabled
  • false. The port is disabled
  port Required Integer Port number
  protocol Required String Protocol that is running on the port. See the GET /discoverRequest/jobs/<job_id> response body for the supported protocols for the device's management ports.
model Optional String (Rack switches only) Model of the device
name Optional String (Rack switches only) Name of the device
newPassword Optional String (Chassis and servers only) New password to be used for managed authentication
os Required String (Rack switches only) Firmware type. This can be one of the following values.
  • CNOS

  • ENOS

password Required String Current password to access the device
recoveryPassword Optional String Recovery password to be used for the device
replaceNtpConfiguration Optional Boolean (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
  • true. (default) Replace the NTP and time zone settings.

  • false. Do not replace the NTP and time zone settings.

securityDescriptor Required Object Information about the authentication enablement and support the associated stored credentials for a managed device
  managedAuthSupported Required for ThinkServer devices Boolean Indicates whether the device supports the ability to choose whether managed authentication is to be used. This can be one of the following values.
  • true. This device supports the ability to choose managed authentication.

  • false. This device does not support the ability to choose managed authentication.

  managedAuthEnabled Required for devices other than ThinkServer Boolean Indicates whether the device uses managed authentication. This can be one of the following values.
  • true. The device uses managed authentication.

  • false. The device uses local authentication.

  roleGroups Optional Array of strings List of role groups that are permitted to view and manage the device. To get a list of available role groups, use GET /roleGroups.

You can specify only role groups to which the current user belongs.

If you do not specify the roleGroups attribute, the default roles groups are assigned. You can obtain the list of default role group using GET /resourceAccessControl.

If you specify the roleGroups attribute with an empty or null value, role groups are not assigned.

Note: If you add devices to a managed chassis, the new devices will belong to the same role groups as the chassis.
  storedCredentials Required if managedAuthEnabled is set to true Object Information about the stored credential that is associated with this device, if applicable
Note: RackSwitch devices support only stored credentials for authenticating to the switches. Manual user credentials are not supported.
    description Optional String Description of the stored credential
    id Required String ID of the stored credential
    userName Optional String Name of the stored credential
serialNumber Optional String (Rack switches only) Serial number for the device
status Optional Object (Rack switches only) Current status
  manageable Optional String Indicates whether the top-of-rack switch is manageable. This can be one of the following values.
  • true. The port is manageable.
  • false. The port is not manageable.
  message Optional String Message
  name Optional Boolean Name
replaceNtpConfiguration Optional Boolean (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
  • true. (default) Replace the NTP and time zone settings.

  • false. Do not replace the NTP and time zone settings.

type Required String Type of device to be managed. This can be one of the following values.
  • Chassis
  • Edge Server. ThinkSystem SE server
  • Lenovo ThinkServer
  • Lenovo Storage
  • Rackswitch
  • Rack-Tower Server. Converged, NeXtScale, System x or ThinkSystem SD, SR, or ST server
username Required String User ID to be used to access the device
Note: RackSwitch devices support only stored credentials (using the storedCredentials attribute) for authenticating to the switches. Manual user credentials using the username and password attributes are not supported and must be empty or null..
uuid Optional String UUID for the device

Request example

The following example discovers and manages a chassis when managed authentication is enabled. (when discovery=true).
[{
   "ipAddresses": ["10.243.3.192", "fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
   "password": "Passw0rd",
   "recoveryPassword": "CME44ibm",
   "securityDescriptor": {
      "managedAuthEnabled": true
   },
   "type": "Chassis",
   "username": "USERID"
}]
The following example discovers and manages a chassis when managed authentication is disabled. (when discovery=true).
[{
   "ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
   "password": "",
   "securityDescriptor": {
      "managedAuthEnabled": false
      "storedCredentials": {
         "id": "2853"
      }
   },
   "type": "Chassis",
   "username": ""
}]
The following example manages a discovered chassis (when discovery=false).
[{
    "ipAddresses": ["10.243.3.55"],
    "managementPorts": [{
        "enabled": false,
        "port": 80,
        "protocol": "http"
    },
    ...,
    {
        "enabled": true,
        "port": 161,
        "protocol": "snmpv3"
    }],
    "password": "xxxxxxxx",
    "recoveryPassword": "xxxxxxxx",
    "securityDescriptor" : {
       "managedAuthEnabled":false,
       "storedCredentials": {
          "description":"A valid user"
          "id":" ED895B48D50D4E34B5DAF1F697CA78B3"
          "userName":"user1",
       }
    } 
    "type": "Chassis",
    "username": "USERID",
    "uuid": "48331a223bf34fba90732b379b837b9c"
}]
The following example discovers and manages a ThinkSystem server (when discovery=true).
[{
   "ipAddresses": ["10.240.211.155","2002:97b:c2bb:830:10:240:211:155","fe80::a94:efff:fe41:be01"],
   "newPassword": null,
   "password": "Passw0rd",
   "recoveryPassword": "Passw0rd",
   "securityDescriptor": {
      "managedAuthEnabled": false,
      "storedCredentials": {
         "id": "2852"
      }
   },
   "type": "Rack-Tower Server",
   "username": null,
   "uuid": "fbb43c13103511e785f2e4a2ced78753",
}]
The following example manages a discovered ThinkSystem server (when discovery=false).
[{
   "enclosureFormFactor": "rack-tower",
   "displayName": "Electron-SIT-2",
   "firmware": [{
      "date": "2018-05-10",
      "build": "TEI325I",
      "version": "1.80"
   },
   {
      "date": "2018-04-24",
      "build": "TEE123G",
      "version": "1.40"
   }],
   "forceManage": true,
   "fruNumber": "01GT946",
   "hostname": "Electron-SIT-2",
   "ipAddresses": ["10.240.211.155","2002:97b:c2bb:830:10:240:211:155","fe80::a94:efff:fe41:be01"],
   "machineType": "7X19",
   "managementPorts": [{
      "protocol": "cimxml-https",
      "port": 5989,
      "enabled": true
   },
   ...,
   {
      "protocol": "rmcp",
      "port": 623,
      "enabled": true
   }],
   "managementProcessor": "lenovo-xclarity-controller",
   "model": "25Z000",
   "name": "Electron-SIT-2",
   "newPassword": null,
   "password": null,
   "recoveryPassword": "",
   "securityDescriptor": {
      "managedAuthEnabled": false,
      "roleGroups": [LXC-ADMIN,LXC-HW-MANAGER],
      "storedCredentials": {
         "description": "test_211.155",
         "id": "2852",
         "userName": "test"
      },
      "uri": "nodes/fbb43c13103511e785f2e4a2ced78753"
   },
   "serialNumber": "ELEC0G604G",
   "server-type": "Rack-Tower Server",
   "status": {
      "name": "UNMANAGED",
      "message": "Unmanaged",
      "manageable": true
   },
   "subType": "",
   "type": "Rack-Tower Server",
   "username": null,
   "uuid": "fbb43c13103511e785f2e4a2ced78753",
}]
The following example manages a discovered ThinkServer device (when discovery=false).
[{
   "displayName": "SN#10.240.197.14",
   "firmware": [{
      "build": "Level 1",
      "date": null,
      "version": "1.1"
   }],
   "forceManage": true,
   "fruNumber": null,
   "hostname": "10.240.197.14",
   "ipAddresses": ["10.240.197.14"],
   "machineType": "70F0",
   "managementPorts": [{
      "enabled": true,
      "port": 443,
      "protocol": "https"
   },
   {
      "enabled": true,
      "port": 80,
      "protocol": "http"
   }],
   "model": "",
   "name": "SN#10.240.197.14",
   "password": "",
   "securityDescriptor": {
      "managedAuthSupported": false,
      "managedAuthEnabled": false,
      "storedCredentials": {
         "id": "353"
      }
   },
   "serialNumber": " ",
   "status": {
      "name": "UNMANAGED",
      "manageable": true
   },
   "type": "Lenovo ThinkServer",
   "username": "",
   "uuid": "fbb43c13103511e785f2e4a2ced78753"
}]
The following example discovers and manages a rack switch running ENOS (when discovery=true).
[{
   "enableHttps": true,
   "enablePassword": "",
   "ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
   "password": "",
   "replaceNtpConfiguration": true
   "securityDescriptor": {
      "managedAuthEnabled": false
      "storedCredentials": {
         "id": "352"
      }
   },
   "type": " Rackswitch ",
   "username": ""
}]
The following example manages a discovered rack switch (when discovery=false).
[{
   "displayName": "Gryphon",
"enableHttps": true,
   "enablePassword": "",
   "forceManage": true,
   "fruNumber": "XXXXXXX     ",
   "hostname": "IBM2-40f2e9b8163d",
   "ipAddresses": [
      "10.243.6.68",
      "fd55:faaf:e1ab:2021:42f2:e9ff:feb8:163d",
      "fe80::42f2:e9ff:feb8:163d"
   ],
   "ipv4Addresses": ["10.243.6.68"],
   "ipv6Addresses": [
      "fd55:faaf:e1ab:2021:42f2:e9ff:feb8:163d",
      "fe80::42f2:e9ff:feb8:163d"
   ],
   "machineType": "1234",
   "model": "IBM",
   "name": "Gryphon",
   "os": "ENOS",
   "password": "DEF",
   "securityDescriptor": {
      "managedAuthEnabled": false,
      "roleGroups": [LXC-ADMIN,LXC-HW-MANAGER],
      "storedCredentials": {
         "id": "352"
      },
      "uri": "switches/2376f7c628fb11e1b72b5cf3fc3c1448"
   },
   "recoveryPassword": null,
   "serialNumber": "IBM0152",
   "status": {
      "message": "Unmanaged",
      "name": "UNMANAGED",
      "manageable": true
   },
   "replaceNtpConfiguration": true,
   "type": "Rackswitch",
   "username": "",
   "uuid": "fc3058cadf8b11d48c9b9b1b1b1b1b58"
}]

Response codes

Code Description
200 OK.
400 Bad request.
403 Forbidden.
404 Not found.
409 Conflict.
500 Internal server error.

Response header

If this POST method results in a job getting started, the response header includes a URI in the form /manageRequest/jobs/{job_id} (for example, /manageRequest/jobs/12) that represents the job that is monitored by the management server. You can use GET /manageRequest/jobs/<job_id> to determine the status of the job. If a job was not successfully started, refer to the response code and response body for details.

Note: A successful response indicates that the request was successfully transmitted and accepted by the management server. It does not indicate that the operation that is associated with the job was successful.

Response body

Attributes Type Description
jobID   ID of the task (job) that was created to manage the device
statusCode   Return code
statusDescription   Description of the return code
result String Results of the request. This can be one of the following values.
  • success. The request completed successfully.
  • failed. The request failed. A descriptive error message was returned.
  • warning. The request completed with a warning. A descriptive error message was returned.
messages Array of objects Information about one or more messages
  explanation String Additional information to clarify the reason for the message
  id String Message identifier of a returned message
  recovery Array of objects Recovery information
    text String User actions that can be taken to recover from the event
    URL String Link to the help system for more information, if available
  text String Message text associated with the message identifier

Response example

{
   "jobID":"42",
   "statusCode":201
   "statusDescription":"Bulk job 138 was created successfully.",
   "result":"success",
   "messages":[],
}