Topology & Smartscape API - Custom device
A custom network device is any part of your environment that can't run DESK OneAgent. Examples include Firewalls, DataPower gateways, cloud databases, and any other network appliance such as a proxy or gateway. By using the DESK API, it's possible for your own networked box to send custom metrics into DESK based on the native properties of these devices, or to write your own scripts that pull the metrics from your networked or cloud-networked box.
DESK will show the custom device on the host and process level within Smartscape, as the device itself can contain a network IP address as well as listening ports. When communication is detected between a OneAgent-instrumented host and the custom device, the connection will be automatically shown within Smartscape. When your custom devices begin to send in metric values, you can use the metrics on the custom charting tile.
As DESK AI and intelligent problem detection and correlation depend on topological information, each custom device should announce its position within your network infrastructure. By providing the correct IP address, along with a detailed description of the custom device properties, you enable DESK to automatically map your custom device into your existing Smartscape environment.
Workflow
This page contains a general description of the request, such as parameters and the response format. Depending on the payload, the usage is different—you can create a custom device or report measurements to an existing custom device.
- See Create custom device via the DESK API to learn how to create a custom device.
- See Report custom device metric via the DESK API to learn how to submit data to a custom device.
POST custom device
The request consumes and produces an application/json
payload.
POST |
|
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
customDeviceId | string |
The ID of the custom device. If you use the ID of an existing device, the respective parameters will be updated. |
path | required |
body | CustomDevicePushMessage |
The JSON body of the request. Contains parameters of a custom device. |
body | optional |
The CustomDevicePushMessage object
Configuration of a custom device.
Element | Type | Description | Required |
---|---|---|---|
displayName | string |
The name of the custom device that will appear in the user interface. |
optional |
group | string |
User defined group ID of entity. The group ID helps to keep a consistent picture of device-group relations. One of many cases where a proper group is important is service detection: you can define which custom devices should lead to the same service by defining the same group ID for them. If you set a group ID, it will be hashed into the DESK entity ID of the custom device. In that case the custom device can only be part of one custom device group. If you don't set the group ID, DESK will create it based on the ID or type of the custom device. Also, the group will not be hashed into the device ID which means the device may switch groups. |
optional |
ipAddresses | string[] |
The list of IP addresses that belong to the custom device. These addresses are used to automatically discover the horizontal communication relationship between this component and all other observed components within Smartscape. Once a connection is discovered, it is automatically mapped and shown within Smartscape. If you send a value (including an empty value), the existing values will be overwritten. If you send |
optional |
listenPorts | integer[] |
The list of ports the custom devices listens to. These ports are used to discover the horizontal communication relationship between this component and all other observed components within Smartscape. Once a connection is discovered, it is automatically mapped and shown within Smartscape. If ports are specified, you should also add at least one IP address or a host name for the custom device. If you send a value, the existing values will be overwritten. If you send |
optional |
type | string |
The technology type definition of the custom device. It must be the same technology type of the metric you're reporting. If you send a value (including an empty value), the existing value will be overwritten. If you send |
optional |
favicon | string |
The icon to be displayed for your custom component within Smartscape. Provide the full URL of the icon file. |
optional |
configUrl | string |
The URL of a configuration web page for the custom device, such as a login page for a firewall or router. |
optional |
properties | object |
The list of key-value pair properties that will be shown beneath the infographics of your custom device. |
optional |
tags | string[] |
List of custom tags that you want to attach to your custom device. |
optional |
series | EntityTimeseriesData[] |
The list of metric values that are reported for the custom device. DESK aggregates all the values you report for a custom device. If you send a value (including an empty value), it will be added to the set of existing values. If you send |
optional |
hostNames | string[] |
The list of host names related to the custom device. These names are used to automatically discover the horizontal communication relationship between this component and all other observed components within Smartscape. Once a connection is discovered, it is automatically mapped and shown within Smartscape. If you send a value, the existing values will be overwritten. If you send |
optional |
The EntityTimeseriesData object
Information about a metric and its data points.
Element | Type | Description | Required |
---|---|---|---|
timeseriesId | string |
The ID of the metric, where you want to post data points. |
required |
dimensions | object |
Dimensions of the data points you're posting. The key of the metric dimension must be defined earlier in the metric definition. |
optional |
dataPoints | array[] |
List of data points. Each data point is an array, containing the timestamp and the value. Timestamp is UTC milliseconds reported as a number, for example: Values can't be reported more than 2 hours into the past! A custom metric must be registered before you can report a metric value. Therefore, the timestamp for reporting a value must be after the registration time of the metric. |
required |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.
{
"displayName": "coffeeMachine",
"group": "myCustomDeviceGroup",
"ipAddresses": [
"10.0.0.1"
],
"listenPorts": [
80
],
"favicon": "https://www.freefavicon.com/freefavicons/food/cup-of-coffee-152-78475.png",
"configUrl": "http://coffee-machine.DESK.internal.com/coffeemachine/manage",
"type": "coffee machine",
"properties": {},
"tags": [
"office-linz"
],
"series": [
{
"timeseriesId": "custom:created.coffee.metric",
"dimensions": {
"office": "Linz"
},
"dataPoints": [
[
1521542929000,
13
]
]
}
],
"hostNames": [
"coffee-machine.DESK.internal.com"
]
}
Response format
Element | Type | Description |
---|---|---|
entityId | string | The DESK entity ID of the newly created custom device. |
groupId | string | The DESK entity ID of the custom device group. |
{
"entityId": "string",
"groupId": "string"
}