Monitored entities API - POST a custom device

Creates or updates a custom device.

The request consumes and produces an application/json payload.

Early Adopter

This request is an Early Adopter release and may be changed in non-compatible way.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/v2/entities/custom
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/entities/custom

Authentication

To execute this request, you need the Write entities (entities.write) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter Type Description In Required
body CustomDeviceCreation

The JSON body of the request. Contains parameters of a custom device.

body optional

Body format

The CustomDeviceCreation object

Configuration of a custom device.

Element Type Description Required
customDeviceId string

The internal ID of the custom device.

If you use the ID of an existing device, the respective parameters will be updated.

required
displayName string

The name of the custom device to be displayed in the user interface.

required
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 Dynatrace 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, Dynatrace 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 null or omit this field, the existing values will be kept.

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 DNS name for the custom device.

If you send a value, the existing values will be overwritten.

If you send null, or an empty value, or omit this field, the existing values will be kept.

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 null or omit this field, the existing value will be kept.

required
faviconUrl 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
dnsNames string[]

The list of DNS 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 null or an empty value; or omit this field, the existing values will be kept.

optional
messageType string The messageType element can hold these values. optional

Possible values

Possible values for the messageType element in the CustomDeviceCreation object:

  • CUSTOM_DEVICE
  • FILTER_VALUE_SUGGESTIONS
  • MULTI
  • MULTI_TYPE
  • SINGLE
  • SINGLE_TYPE

Response

Response codes

Code Description
201

Success

204

Success

400

Failed. The input is invalid.

Response body

The CustomDeviceCreationResult object

The short representation of a newly created custom device.

Element Type Description
entityId string

The Dynatrace entity ID of the custom device.

groupId string

The Dynatrace entity ID of the custom device group.

Example

In this example, the request creates a custom device with the ID of restExample and the following parameters:

  • type: F5-Firewall
  • IP address 172.16.115.211
  • listen port 9999

The request also specifies some additional parameters.

The API token is passed in the Authorization header.

The request returns the IDs of the custom device (see entityId) and its group (see groupId) as confirmation.

You can download or copy the example request body to try it out on your own.

Curl

curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/entities/custom' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
--data-raw '{
  "customDeviceId": "restExample",
  "displayName" : "F5 Firewall 24",
  "ipAddresses" : ["172.16.115.211"],
  "listenPorts" : ["9999"],
  "type" : "F5-Firewall",
  "favicon" : "http://assets.dynatrace.com/global/icons/f5.png",
  "configUrl" : "http://192.128.0.1:8080",  
  "properties" : {
    "Sample Property 1": "Sample value 1"
  }
}
'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/entities/custom

Request body

Download
{
  "customDeviceId": "restExample",
  "displayName" : "F5 Firewall 24",
  "ipAddresses" : ["172.16.115.211"],
  "listenPorts" : ["9999"],
  "type" : "F5-Firewall",
  "favicon" : "http://assets.dynatrace.com/global/icons/f5.png",
  "configUrl" : "http://192.128.0.1:8080",  
  "properties" : {
    "Sample Property 1": "Sample value 1"
  }
}

Response body

{
  "entityId": "CUSTOM_DEVICE-1525F193C0578E2C",
  "groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}

Response code

201