Skip to main content

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 username and password is required.

Request URL

POST https://{management_server_IP}/manageRequest

Query parameters

ParametersRequired / OptionalDescription
discovery={Boolean}OptionalIndicates 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.
AttributesRequired / OptionalTypeDescription
enableHttpsOptionalBoolean(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.
enablePasswordOptionalString(Rack switches running ENOS only) Enable password that is used to enter Privileged Exec Mode on the switch
forceManageOptionalBooleanIndicates 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.
ipAddressesRequiredArray of stringsList of device IP addresses or fully-qualified domain names
newPasswordOptionalString(Chassis and servers only) New password to be used for managed authentication
passwordRequiredStringCurrent password to access the device
recoveryPasswordOptionalStringRecovery password to be used for the device
replaceNtpConfigurationOptionalBoolean(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.
securityDescriptorRequiredObjectInformation about the authentication enablement and support the associated stored credentials for a managed device
 identityManagementSystemRequired if identityManagementSystemEnabled is trueString(Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable
  addressRequiredStringIP 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).
  appIdOptionalStringApplication ID from CyberArk

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

  folderOptionalStringFolder 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.

  nameOptionalStringType of the identity-management system. This value is always CyberArk
  safeOptionalStringSafe from CyberArk

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

  usernameRequiredStringName of the user account for the device
 identityManagementSystemEnabledOptionalStringIndicates 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.
 managedAuthSupportedRequired for ThinkServer devicesBooleanIndicates 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.
 managedAuthEnabledRequired for devices other than ThinkServerBooleanIndicates 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.
 publicAccessOptionalBoolean 
 roleGroupsOptionalArray of stringsList 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.
 storedCredentialsRequired if managedAuthEnabled is set to trueObjectInformation 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.
  descriptionOptionalStringDescription of the stored credential
  idRequiredStringID of the stored credential
  userNameOptionalStringName of the stored credential
typeRequiredStringType 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
sshPortOptionalInteger(Mellanox switches only) SSH port to use for management

If not specified, port 22 is used by default.

usernameRequiredStringUser 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.
AttributesRequired / OptionalTypeDescription
displayNameOptionalString(Rack switches only) Name of the device
enableHttpsOptionalBoolean(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.
enclosureFormFactorOptionalString(IMM, IMM2, XCC, or XCC2 only) Form factor of the device. This can be one of the following values.
  • rack-tower
  • dense-computing
enablePasswordOptionalString(Rack switches running ENOS only) Enable password that is used to enter Privileged Exec Mode on the switch
firmwareOptionalArray of stringsInformation about installed firmware
 buildRequiredStringBuild number
 dateRequiredStringRelease date
 versionRequiredStringVersion number
forceManageOptionalBooleanIndicates 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.
fruNumberOptionalString(Rack switches only) FRU number
hostnameOptionalString(Rack switches only) hostname of the device
ipAddressesRequiredArray of stringsList of device IP addresses or fully-qualified domain names
ipv4AddressesOptionalArray of strings(Rack switches only) List of IPv4 IP addresses
ipv6AddressesOptionalArray of strings(Rack switches only) List of IPv6 IP addresses
machineTypeRequired for ThinkSystem servers; otherwise, optionalStringMachine type
managementPortsOptional for switches; otherwise, requiredArrayList of device management ports
 enabledRequiredBooleanIndicates whether the port enabled. This can be one of the following values.
  • true. The port is enabled
  • false. The port is disabled
 portRequiredIntegerPort number
 protocolRequiredStringProtocol 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.
managementProcessorRequired for ThinkSystem devices; otherwise, optionalString(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
modelOptionalString(Rack switches only) Model of the device
nameOptionalString(Rack switches only) Name of the device
newPasswordOptionalString(Chassis and servers only) New password to be used for managed authentication
osRequired for CNOS and ENOS switchesString(Rack switches only) Firmware type. This can be one of the following values.
  • CNOS
  • ENOS
passwordRequiredStringCurrent password to access the device
recoveryPasswordOptionalStringRecovery password to be used for the device
replaceNtpConfigurationOptionalBoolean(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.
securityDescriptorRequiredObjectInformation about the authentication enablement and support the associated stored credentials for a managed device
 identityManagementSystemRequired if identityManagementSystemEnabled is trueString(Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable
  addressRequiredStringIP 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).
  appIdOptionalStringApplication 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)

  folderOptionalStringFolder 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.

  nameOptionalStringType of the identity-management system. This value is always CyberArk.
  safeOptionalStringSafe from CyberArk

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

  usernameRequiredStringName of the user account for the device
  uriOptionalStringDevice URI
 identityManagementSystemEnabledOptionalStringIndicates 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.
 managedAuthSupportedRequired for ThinkServer devicesBooleanIndicates 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.
 managedAuthEnabledRequired for devices other than ThinkServerBooleanIndicates 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.
 publicAccessOptionalBooleanIndicates 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.
 roleGroupsOptionalArray of stringsList 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.
 storedCredentialsRequired if managedAuthEnabled is set to trueObjectInformation 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.
  descriptionOptionalStringDescription of the stored credential
  idRequiredStringID of the stored credential
  userNameOptionalStringName of the stored credential
serialNumberOptionalString(Rack switches only) Serial number for the device
statusOptionalObject(Rack switches only) Current status
 manageableOptionalStringIndicates 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.
 messageOptionalStringMessage
 nameOptionalBooleanName
replaceNtpConfigurationOptionalBoolean(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.
subTypeRequired for ThinkSystem DB series and NVIDIA Mellanox switchesStringDevice subtype. This can be one of the following values.
  • Lenovo ThinkSystem DB Series Switches
  • NVIDIA Mellanox Switches
server-typeOptionalString(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.
typeRequiredStringType 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
usernameRequiredStringUser 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.
uuidOptionalStringUUID 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

CodeDescriptionComments
200OKThe request completed successfully.
400Bad RequestA 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.
403ForbiddenThe 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.
404Not foundA specified resource cannot be found. A descriptive error message is returned in the response body.
409ConflictThere is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500Internal Server ErrorAn 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/{bulk_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

AttributesTypeDescription
jobID ID of the task (job) that was created to manage the device
statusCode Return code
statusDescription Description of the return code
resultStringResults 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.
messagesArray of objectsInformation about one or more messages
 explanationStringAdditional information to clarify the reason for the message
 idStringMessage identifier of a returned message
 recoveryArray of objectsRecovery information
  textStringUser actions that can be taken to recover from the event
  URLStringLink to the help system for more information, if available
 textStringMessage 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":[],
}