Use the following APIs to create, get, update, and delete a filtered device list.

Required Permissions

You must be a Monitoring Administrator or a Device Administrator to perform these operations.

Create a Filtered Device List

Required Permissions

You must have the Create Filter Definition permission to perform this operation.

Description

Create a filtered device list based on a user-defined filter definition and return the ID of the list. Use the id to make a GET call of the filtered device list to view the list of devices.

API
/api/filter-results/
Deprecated: /api/filters
Method
POST
Required Parameters
Name Description
projection
  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • dataSource

    string

    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

startTimeMs

int64

Start time for metric filters

retentionTimeSec

string

Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it. This parameter is deprecated from version 0.7 onwards.
filter

string

Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs.
oredOperatorValuePair
  • operator

    string

    • EQUAL_TO
    • NOT_EQUAL_TO
    • GREATER_THAN
    • GREATER_THAN_EQUAL_TO
    • LESS_THAN
    • LESS_THAN_EQUAL_TO
    • CONTAINS
Enter one of the following values:
  • valueInt64

    int64

  • valueString

    string

  • valueBoolean

    boolean

  • valueDouble

    double

keyObj
  • valueType
    string
    • INT64
    • DOUBLE
    • STRING
    • BOOLEAN
  • dataSource
    string
    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • isPeriodRequired

    string

    Whether or not the key requires a period. For example, metric filter keys require a period (start/end time).

  • keyType
    • PROJECTABLE
    • FILTERABLE
    • BOTH
  • display_unit

    The unit of value if the key is a metric key.

  • factor

    The conversion factor to convert from the reported unit of metric to the display unit of metric. This parameter is deprecated from version 0.7 onwards.

  • display_name

    The display name of the filter.

endTimeMs

int64

End time for metric filters.
offsetMs

int64

A time amount to be subtracted from the current time, for the start time of a relative time-ranged query.
Note: You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.
limit

int32

The maximum number of results.
isRelative

boolean

Indicate whether the time range is relative or not.
templateId

string

Device template Ids.
Input Example
{
"filter": [
{
"keyObj": {
"dataSource": "DEVICEMGMT_SERVICE",
"key": "id",
"keyQualifier": "device",
"valueType": "STRING",
"keyType": "BOTH"
},
"oredOperationValuePair": [
{
"operator": "2",
"valueString": "1"
}
]
}
],
"projection": [
{
"dataSource": "DEVICEMGMT_SERVICE",
"key": "name",
"keyQualifier": "device"
}
],
"templateId": [
"2c18410f-fe2e-48e6-ae13-8b040704916e"
],
"limit": 2
}
Response
{
  "id": "string"
}

Get a Filtered Device List

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API
/api/filter-results/{id}
Deprecated: /api/filters/{id}
Method
GET
Required Parameters
Name Description
id

string

ID of the filtered device list.
Response
{
  "filteredDevice": [
    {
      "keyValuePair": [
        {
          "valueString": "string",
          "key": "string",
        }
      ],
      "id": "string"
    }
  ],
  "aggregationTaskStatus": "STARTED",
  "pageInfo": {
    "totalPages": 2,
    "totalElements": 2",
    "page": 1,
    "pageSize": 1
  }
}

Delete a Filtered Device List

Required Permissions

You must have the Delete Filter Definition permission to perform this operation.

API
/api/filter-results/{id}
Deprecated: /api/filters/{id}
Method
DELETE
Required Parameters
Name Description
id

string

ID of the filtered device list.
Response
{}

Get all Keys for Filters and Projections

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API
/api/filter-keys
Deprecated: /api/filters/filter-keys
Method
GET
Required Parameters
None
Response
{
  "keyObjs": [
    {
      "valueType": "BOOLEAN",
      "keyQualifier": "string",
      "isPeriodRequired": false,
      "dataSource": "CAMPAIGN_SERVICE",
      "key": "string"
      "keyType": "BOTH"
    },
    {
      "valueType": "INT64",
      "keyQualifier": "string",
      "isPeriodRequired": true,
      "dataSource": "METRIC_SERVICE",
      "key": "string",
      "keyType": "FILTERABLE",
      "displayUnit" :"%",
      "factor": 1
    }
  ]
}

Save a Filter Definition

Required Permissions

You must have the Edit Filter Definition permission to perform this operation.

API
/api/filter-definitions
Deprecated: /api/filters/definitions
Method
POST
Required Parameters
Name Description
projection
  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • dataSource

    string

    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

startTimeMs

int64

Start time for metric filters.

retentionTimeSec

string

Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it.
filter

string

Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs.
oredOperatorValuePair
  • operator

    string

    • EQUAL_TO
    • NOT_EQUAL_TO
    • GREATER_THAN
    • GREATER_THAN_EQUAL_TO
    • LESS_THAN
    • LESS_THAN_EQUAL_TO
    • CONTAINS
Enter one of the following values:
  • valueInt64

    int64

  • valueString

    string

  • valueBoolean

    boolean

  • valueDouble

    double

keyObj
  • valueType
    string
    • INT64
    • DOUBLE
    • STRING
    • BOOLEAN
  • dataSource
    string
    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • isPeriodRequired

    string

    Whether or not the key requires a period. For example, metric filter keys require a period (start/end time).

  • keyType
    • PROJECTABLE
    • FILTERABLE
    • BOTH
  • display_unit

    The unit of value if the key is a metric key.

  • factor

    The conversion factor to convert from the reported unit of metric to the display unit of metric.

endTimeMs

int64

End time for metric filters.
isRelative

boolean

Indicate whether the time range is relative or not.
templateId

string

Device template Ids.
Input Example
{
          name: "string",
          template_id: ["string", "string"],
          filter: [
             key_obj: {
                data_source: "DEVICEMGMT_SERVICE",
                key: "string",
                key_qualifier: "string",
                value_type: "STRING",
                is_period_required: false,
                key_type: "BOTH"
               },
               ored_operation_value_pair: [
                 {
                   operator: "EQUAL_TO",
                   value_string: "blue"
                 },
                 {
                   operator: "EQUAL_TO",
                   value_string: "red"
                 }
                ]
              },
            {
             key_obj: {
             data_source: "CAMPAIGN_SERVICE",
              key: "string",
              key_qualifier: "",
              value_type: "STRING",
              is_period_required: false,
              key_type: "BOTH"
            },
            ored_operation_value_pair: [
              {
                operator: "EQUAL_TO",
                value_string: "INITIALIZED"
              }
            ]
           },
           {
             key_obj: {
               "dataSource": "METRIC_SERVICE",
               "key": "string",
               "keyType": "FILTERABLE",
               "valueType": "INT64",
               "keyQualifier": "string",
               "isPeriodRequired": true, 
               "displayUnit" :"%",
               "factor": 1
           }
           },
           ored_operation_value_pair: [
             {
               operator: "GREATER_THAN",
               value_int64: 90
             }
           ]
          }
         ],
         projection: [
            {
               "data_source": "CAMPAIGN_SERVICE",
               "key": "string",
               "key_qualifier": ""
            }
         ],
         start_time_ms: 1500000001000,
         end_time_ms: 1500000002000
        }
Response
{
  "id": "string"
}

Update a Filter Definition

Required Permissions

You must have the Edit Filter Definition permission to perform this operation.

API
/api/filter-definitions/{id}
Deprecated: /api/filters/definitions/{id}
Method
PUT
Required Parameters
Name Description
projection
  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • dataSource

    string

    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

startTimeMs

int64

Start time for metric filters.

retentionTimeSec

string

Retention time of a filtered device list.
filter

string

Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs.
oredOperatorValuePair
  • operator

    string

    • EQUAL_TO
    • NOT_EQUAL_TO
    • GREATER_THAN
    • GREATER_THAN_EQUAL_TO
    • LESS_THAN
    • LESS_THAN_EQUAL_TO
    • CONTAINS
Enter one of the following values:
  • valueInt64

    int64

  • valueString

    string

  • valueBoolean

    boolean

  • valueDouble

    double

keyObj
  • valueType
    string
    • INT64
    • DOUBLE
    • STRING
    • BOOLEAN
  • dataSource
    string
    • DEVICEMGMT_SERVICE: Device management micro service.
    • CAMPAIGN_SERVICE: Campaign management micro service.
    • METRIC_SERVICE: Metric query micro service.
  • key

    string

  • keyQualifier

    string

    Key qualifier to specify the location of the key when the key is in a nested document.

  • isPeriodRequired

    string

    Whether or not the key requires a period-like metric key.

  • keyType
    • PROJECTABLE
    • FILTERABLE
    • BOTH
  • display_unit

    The unit of value if the key is a metric key.

  • factor

    The conversion factor to convert from the reported unit of metric to the display unit of metric.

endTimeMs

int64

End time for metric filters.
offsetMs

int64

A time amount to be subtracted from the current time, for the start time of a relative time-ranged query.
Note: You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.
isRelative

boolean

Indicate whether the time range is relative or not.
templateId

string

Device template Ids.
Input Example
{
          name: "string",
          template_id: ["string", "string"],
          filter: [
             key_obj: {
                data_source: "DEVICEMGMT_SERVICE",
                key: "string",
                key_qualifier: "string",
                value_type: "STRING",
                is_period_required: false,
                key_type: "BOTH"
               },
               ored_operation_value_pair: [
                 {
                   operator: "EQUAL_TO",
                   value_string: "blue"
                 },
                 {
                   operator: "EQUAL_TO",
                   value_string: "red"
                 }
                ]
              },
            {
             key_obj: {
             data_source: "CAMPAIGN_SERVICE",
              key: "string",
              key_qualifier: "",
              value_type: "STRING",
              is_period_required: false,
              key_type: "BOTH"
            },
            ored_operation_value_pair: [
              {
                operator: "EQUAL_TO",
                value_string: "INITIALIZED"
              }
            ]
           },
           {
             key_obj: {
             data_source: "METRIC_SERVICE",
              key: "string",
              key_qualifier: "",
              value_type: "NUMBER",
              is_period_required: true,
              key_type: "FILTERABLE"
           },
           ored_operation_value_pair: [
             {
               operator: "GREATER_THAN",
               value_int64: 90
             }
           ]
          }
         ],
         projection: [
            {
               "data_source": "CAMPAIGN_SERVICE",
               "key": "string",
               "key_qualifier": ""
            }
         ],
         start_time_ms: 1500000001000,
         end_time_ms: 1500000002000
        }
Response
{
  "id": "string"
}

Get a Filter Definition by ID

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API
/api/filter-definitions/{id}
Deprecated: /api/filters/definitions/{id}
Method
GET
Required Parameters
Name Description
id

string

ID of the filter definition.
Response
{
  "id": "string",
  "name": "string",
  "templateId": ["string", "string"],
  "filter": [
       {
          "keyObj": {
              "dataSource": "DEVICEMGMT_SERVICE",
              "key": "type",
              "keyQualifier": "device",
              "valueType": "STRING"
          }
        }
    ],
    "projection": [
        {
            "dataSource": "CAMPAIGN_SERVICE",
            "key": "string"
        },
        {
            "dataSource": "DEVICEMGMT_SERVICE",
            "key": "string",
            "keyQualifier": "string"
        }
    ],
    "startTimeMs": 1500000000000,
    "endTimeMs": 1500000001000,
    "tenantId": "string",
    "createdTime": 1500000002000,
    "lastUpdatedTime": 1500000003000,
    "createdBy": "string",
    "lastUpdatedBy": "string",
    "updateVersion": 2
}

Delete a Filter Definition by ID

Required Permissions

You must have the Delete Filter Definition permission to perform this operation.

API
/api/filter-definitions/{id}
Deprecated: /api/filters/definitions/{id}
Method
DELETE
Required Parameters
Name Description
id

string

ID of the filter definition.
Response
{}

Get a Filter Definition List

Required Permissions

You must have the View Filter Definition permission to perform this operation.

API
/api/filter-definitions
Deprecated: /api/filters/definitions
Method
GET
Required Parameters
None
Response
{
  "filterDefinitionObjIdName": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "pageInfo": {
    "page": 1,
    "pageSize": 10
    "totalElements": "1",
    "totalPages": "1"
    
  }
}