Decommissioning robots using UIMAPI
Article ID: 427680
Updated On:
Products
Issue/Introduction
This article outlines the process for deleting/decommissioning/removing robots using the UIMAPI, in the case where you want to completely remove a robot from the DX UIM environment.
Environment
DX UIM 23.4.2 (aka 23.4 CU2) or later
UIMAPI 23.4.2+
Resolution
From DX UIM 23.4.2 forward, it is possible to use the UIMAPI to perform several bulk actions related to automatically decommissioning robots.
The two UIMAPI calls most commonly used together for this purpose are:
/uimapi/devices/devices_bulk_list -- to retrieve the csID for one or more devices which you want to delete
/uimapi/devices/bulk_actions/ -- to execute the deletion
Usage examples:
/uimapi/devices/devices_bulk_list
HTTP Method: POST
Purpose: This call is used to return one or more csId (Computer System IDs) when supplied with one or more of the following parameters:
robot name
ip address
origin
Examples:
A. Retrieving a single csId by IP address
Request Body (JSON):
[
{
"ip": "10.10.10.10"
}
]
Response (XML/HashMap):
<HashMap>
<results>
<csId>5</csId>
<name>my-robot</name>
<ip>10.10.10.10</ip>
</results>
</HashMap>
Result: csId is 5
B. Retrieving multiple csIds by IP address
Request Body (JSON):
[
{
"ip": "10.10.10.10"
},
{
"ip": "10.10.10.11"
}
]
Response (XML/HashMap - List):
<HashMap>
<results>
<csId>3</csId>
<name>my-robot</name>
<ip>10.10.10.10</ip>
</results>
<results>
<csId>5</csId>
<name>my-other-robot</name>
<ip>10.10.10.11</ip>
</results>
</HashMap>
Result: csIds are 3 and 5
C. Retrieving a csId by name
Request Body (JSON):
[
{
"name": "my-robot"
}
]
Response (XML/HashMap):
<HashMap>
<results>
<csId>3</csId>
<name>my-robot</name>
<ip>10.10.10.10</ip>
</results>
</HashMap>
Result: csId is 3
The csId value(s) must be captured in your program/script logic and used in the next callback.
/uimapi/devices/bulk_actions/
HTTP Method: POST
Purpose: This API performs various bulk actions. For decommissioning, it requires the csID from the previous call along with specific parameters, one of which defines which bulk action to take (in this case, the "delete_devices" bulk action).
Key Parameters for Deletion:
|
Parameter |
Type |
Description |
|
deepClean |
boolean |
Set to true to automatically uninstall the robot and remove from inventory in one operation. |
|
preventReDiscovery |
boolean |
Set to true to prevent the robot from being automatically rediscovered. |
|
acknowledgeAlarms |
boolean |
Set to true to acknowledge any open alarms for the device. |
|
deleteMeasurements |
boolean |
Set to true to delete associated QoS measurements. |
|
action |
string |
Must be delete_devices. |
|
ids |
string or array of strings |
The list of csIds to delete (e.g., ["3", "5"]). |
Example: Deleting a single robot
This example deletes the robot with csId 3 ("my-robot") without a deep clean or preventing rediscovery.
Request Body (JSON):
{
"deepClean": false,
"preventReDiscovery": false,
"acknowledgeAlarms": true,
"deleteMeasurements": false,
"action": "delete_devices",
"ids": [
"3"
]
}
Example: Deleting multiple robots
This example deletes robots with csIds 3 and 5.
Request Body (JSON):
{
"deepClean": false,
"preventReDiscovery": false,
"acknowledgeAlarms": true,
"deleteMeasurements": false,
"action": "delete_devices",
"ids": [
"3",
"5"
]
}
Successful Response (XML/JobResponse):
If successful, the API responds with an ID for the deletion job, which can be seen in Delete Devices Status in OC:
<JobResponse>
<jobId>123</jobId>
</JobResponse>
Additional Information
The csId value for a system can also be found by viewing the Device Details for that system in the Operator Console Inventory. The "ID" value for a system is the same as the csId.
This is also equivalent to the cs_id column in the CM_COMPUTER_SYSTEM table.
More detailed information about the available callbacks can be found at the following link:
(From DX UIM v23.4 CU2) Consideration for Bulk On-boarding/Decommissioning of Devices
Feedback
