POST /manageRequest

Use this 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
  identityManagementSystem Required if identityManagementSystemEnabled is true String (Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable
    address Required String IP address or hostname where the user account is stored as defined in CyberArk. This is typically the IP address of the Lenovo XClarity Controller or external LDAP server (if applicable).
    appId Optional String Application ID from CyberArk

If you specify the appID, you must also specify safe and folder.

    folder Optional String Folder from CyberArk

If you specify the appID, you must also specify safe and folder. If the onboarded account is not in a folder, specify an empty string.

    name Optional String Type of the identity-management system. This value is always CyberArk
    safe Optional String Safe from CyberArk

If you specify the appID, you must also specify safe and folder.

    username Required String Name of the user account for the device
  identityManagementSystemEnabled Optional String Indicates whether to use an identity-management system for authentication. This can be one of the following values.
  • true. An identity-management system is to authenticate this device.
  • false. An identity-management system is not used to authenticate this device. In this case, either manually entered credentials or stored credentials must be used.
Note: Identity management systems can be used to authenticate only ThinkSystem and ThinkAgile servers.
  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.

  publicAccess Optional Boolean  
  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
  • IBM Tape. IBM tape library
  • Lenovo ThinkServer
  • Lenovo Storage
  • Rackswitch
  • Rack-Tower Server. ThinkSystem SD, ThinkSystem SR, or ThinkSystem ST, System x, Converged, or NeXtScale 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..
The following example discovers and manages a server when managed authentication is enabled and uses CyberArk for authentication. (when discovery=true).
[{
   "ipAddresses": ["192.0.2.0"],
   "forceManage": true,
   "password": null,
   "securityDescriptor": {
      "identityManagementSystem": {
         "address" : "192.0.2.0",
         "appId": "LXCA",
         "name" : "CyberArk",
         "safe": "Test",
         "username": "USERID"
      },
      "identityManagementSystemEnabled": true,
      "managedAuthEnabled": true,
      "managedAuthSupported": true,
      "publicAccess": false,
      "storedCredentials":null
   },
   "type": "Rack-Tower Server",
   "username": null
}]
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 server when managed authentication is enabled using an identity management system (when discovery=true).
[{
   "ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
   "password": "",
   "securityDescriptor": {
       "IMSCredentialsId": "1234",
       "managedAuthEnabled": true
   },
   "type": "Server",
   "username": ""
}]
The following example discovers and manages a chassis when managed authentication is disabled using a stored credential (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": ""
}]
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, XCC, or XCC2 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
firmware Optional Array of strings Information about installed firmware
  build Required String Build number
  date Required String Release date
  version Required String Version number
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
machineType Required for ThinkSystem servers; otherwise, optional String Machine type
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.
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
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 for CNOS and ENOS switches 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
  identityManagementSystem Required if identityManagementSystemEnabled is true String (Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable
    address Required String IP address where the user account is stored as defined in CyberArk. This is typically the IP address of the Lenovo XClarity Controller or external LDAP server (if applicable).
    appId Optional String Application ID from CyberArk

If you specify the appID, you must also specify safe and folder.

If you do not specify appID, Lenovo XClarity Administrator uses the paths that are already defined to identify the onboarded accounts in CyberArk (see GET /identityManagementSystems/cyberark/paths)

    folder Optional String Folder from CyberArk

If you specify the appID, you must also specify safe and folder. If the onboarded account is not in a folder, specify an empty string.

    name Optional String Type of the identity-management system. This value is always CyberArk.
    safe Optional String Safe from CyberArk

If you specify the appID, you must also specify safe and folder.

    username Required String Name of the user account for the device
    uri Optional String Device URI
  identityManagementSystemEnabled Optional String Indicates whether to use an identity-management system for authentication. This can be one of the following values.
  • true. An identity-management system is to authenticate this device.
  • false. An identity-management system is not used to authenticate this device. In this case, either manually entered credentials or stored credentials must be used.
Note: Identity management systems can be used to authenticate only ThinkSystem and ThinkAgile servers.
  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.
  publicAccess Optional Boolean Indicates whether the device can be accessed by all role groups. This can be one of the following values.
  • true. The resource is can be access by all role group.
  • false. The resource is restricted to specific role groups.
  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.

subType Required for ThinkSystem DB series and NVIDIA Mellanox switches String Device subtype. This can be one of the following values.
  • Lenovo ThinkSystem DB Series Switches
  • NVIDIA Mellanox Switches
server-type Optional String (Servers only) Type of server to be managed. This can be one of the following values.
  • Edge Server. ThinkSystem SE server
  • ITE. Flex System server
  • Lenovo ThinkServer. ThinkServer server
  • NeXtScale. NeXtScale server
  • Rack-Tower Server. ThinkSystem SD, ThinkSystem SR, or ThinkSystem ST, System x, Converged, or NeXtScale server
  • SCU. storage device.
type Required String Type of device to be managed. This can be one of the following values.
  • Chassis
  • Edge Server. ThinkSystem SE server
  • IBM Tape. IBM tape library
  • Lenovo ThinkServer
  • Lenovo Storage
  • Rackswitch
  • Rack-Tower Server. ThinkSystem SD, ThinkSystem SR, or ThinkSystem ST, System x, Converged, or NeXtScale 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
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 using an identity management system (when discovery=true).
[{
   "displayName": "Cosmo-157",
   "enclosureFormFactor": "rack-tower",
   "firmware": [{
      "build": "CDI352T",
      "date": "2020-04-25",
      "version": "4.20"
   }, {
      "build": "TEE155I",
      "date": "2020-03-27",
      "version": "2.60"
   }],
   "forceManage": true,
   "fruNumber": "00MX680",
   "hostname": "XCC-7Y02-0123456789",
   "ipAddresses": [
      "192.0.2.0",
      "fd55:faaf:e1ab:2021:a94:efff:fe4f:5769",
      "fe80::a94:efff:fe4f:5769"
   ],
   "machineType": "7Y02",
   "managementPorts": [{
      "enabled": true,
      "port": 5989,
      "protocol": "cimxml-https"
   }, ..., {
      "enabled": true,
      "port": 623,
      "protocol": "rmcp"
   }],
   "managementProcessor": "lenovo-xclarity-controller",
   "model": "RCZ000",
   "name": "Cosmo-157",
   "password": null,
   "recoveryPassword": "",
   "securityDescriptor": {
      "identityManagementSystem": {
         "address" : "192.0.2.0",
         "appId": "LXCA",
         "name" : "CyberArk",
         "safe": "Test",
         "username": "USERID"
      },
      "identityManagementSystemEnabled": true,
      "managedAuthEnabled": true,
      "managedAuthSupported": true,
      "publicAccess": false,
      "storedCredentials":null
   },
   "serialNumber": "123456789",
   "status": {
      "manageable": true
      "message": "Unmanaged",
      "name": "UNMANAGED",,
   },
   "subType": "",
   "server-type": "Rack-Tower Server",
   "type": "Rack-Tower Server",
   "username": null,
   "uuid": "a6df710c8b7d11e78c2786fa5e924c8c"
}]
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 Comments
200 OK The request completed successfully.
400 Bad Request A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body.
403 Forbidden The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request.
404 Not found A specified resource cannot be found. A descriptive error message is returned in the response body.
409 Conflict There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500 Internal Server Error An internal error occurred. A descriptive error message is returned in the response body.

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
The following example is returned if the request is successful.
{
   "jobID":"42",
   "statusCode":201
   "statusDescription":"Bulk job 138 was created successfully.",
   "result":"success",
   "messages":[],
}