Enterprise 11: Request device details

Use this API to retrieve a list of devices that are available for bot deployment.

Prerequisites

Roles and license

You need to authenticate as a user with an Unattended bot runner license.

  • URL:
    http://<your_control_room_url>/v2/devices/list
  • Method: POST
Supported filterable parameters:
id
The numeric identifier for a device.
  • Field: id
  • Type: integer 
{
  "filter": {
    "operator": "eq",
    "value": "7",
    "field": "id"
  }
}
hostName
The name of the registered device.
  • Field: hostName
  • Type: string 
{
  "filter": {
    "operator": "substring",
    "value": "AA",
    "field": "hostName"
  }
}
userId
A unique numeric identifier for the user associated with the registered device.
  • Field: userId
  • Type: long 
{
  "filter": {
    "operator": "eq",
    "value": "13",
    "field": "userId"
  }
}

This task requests a list of all devices with a specific string in the name parameter and modified after a specific date. Use the list in the response to identify which devices are connected and available to run bots. All the devices in the list are registered Bot Runners.

Procedure

  1. Add an authentication token to the request header.
    Note: Use the Enterprise 11 Authentication API to generate a JSON Web Token.
  2. Select the POST method.
  3. Enter the URL for the API http://<your_control_room_url>/v2/devices/list.
  4. Enter a request filter to limit the number of registered devices listed in the response. By wrapping filters in the logical operator "and," you can build a detailed filter. 
    {
  "filter": {
    "operator": "and",
    "operands": [
      {
        "operator": "ne",
        "value": "7",
        "field": "id"
      },
      {
        "operator": "substring",
        "value": "ec",
        "field": "hostName"
      }
    ]
  }
}
  5. Send the request.
    • In a REST client, click SEND.
    • In the Swagger interface, click Execute.

    Response body:

    The response includes 2 registered devices out of 8 that meet the filter criteria.
    {
  "page": {
    "offset": 0,
    "total": 8,
    "totalFilter": 2
  },
  "list": [
    {
      "id": "1",
      "type": "BOT_CREATOR",
      "hostName": "EC2AMAZ-R8AC9KV",
      "userId": "2",
      "userName": "docbotcreator",
      "status": "DISCONNECTED",
      "poolName": "",
      "fullyQualifiedHostName": "EC2AMAZ-R8AC9KV"
    },
    {
      "id": "14",
      "type": "BOT_RUNNER",
      "hostName": "EC2AMAZ-R8AC9KV",
      "userId": "3",
      "userName": "docbotrunner",
      "status": "DISCONNECTED",
      "poolName": "Finance Test Device Pool",
      "fullyQualifiedHostName": "EC2AMAZ-R8AC9KV"
    }
  ]
}

Next steps

Note the ids for devices with type of BOT_RUNNER and status of CONNECTED. Write down the device's id. The device id and bot id are used to deploy bots on Bot Runners.