External synthetic API - POST external monitors to DESK

Pushes external synthetic monitors, locations, and monitor execution results to DESK.

The request consumes an application/json payload.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/ext/tests
  • SaaS https://{your-environment-id}.live.dexp.ae/api/v1/synthetic/ext/tests

Parameters

Parameter Type Description In Required
ExternalSyntheticTests ExternalSyntheticTests

The JSON body of the request, containing external synthetic monitors, locations, and results.

 body required

The ExternalSyntheticTests object

Element Type Description Required
syntheticEngineName string

The type of the external synthetic monitor.

 required
syntheticEngineIconUrl string

The URL of the external synthetic monitor icon.

 optional
messageTimestamp integer

The timestamp of the message creation, in UTC milliseconds.

 required
locations ExternalSyntheticLocation[]

The list of external synthetic locations.

 required
tests ExternalSyntheticMonitor[]

The list of external synthetic monitors.

 required
testResults ExternalSyntheticTestResult[]

The list of results of external synthetic monitor execution.

 optional

The ExternalSyntheticTestResult object

The results of external synthetic monitor execution.

Element Type Description Required
id string

The ID of the external synthetic monitor.

 required
totalStepCount integer

Number of steps in the monitor.

 required
locationResults ExternalSyntheticLocationTestResult[]

Results of external monitor executions per location.

 required

The ExternalSyntheticLocationTestResult object

Results of external monitor executions per location.

Element Type Description Required
id string

The ID of the location.

 required
startTimestamp integer

The timestamp of text execution start, in UTC milliseconds.

 required
success boolean

The step is successful (true) or failed (false) - will influence availability timeseries.

 required
responseTimeMillis integer

The overall response time of the monitor from this location, in milliseconds.

If absent, it is calculated as the sum of response times of all steps.

 optional
stepResults SyntheticMonitorStepResult[]

Results of individual monitor steps.

 required
successRate number

The overall availability of the monitor from this location, percent.

If absent, calculated as the number of successful steps compared to the overall number of steps.

 optional

The SyntheticMonitorStepResult object

The result of the individual step of a synthetic monitor.

Element Type Description Required
id integer

ID of the step. It is unique within the test definition.

 required
startTimestamp integer

The timestamp of text step execution, UTC milliseconds.

 required
responseTimeMillis integer

The response time of the step, in milliseconds.

Absent when no meaningful response time is available (as may be the case for certain error conditions such as a misconfigured step script).

 optional
error SyntheticMonitorError

The error message of the step.

 optional

The SyntheticMonitorError object

The error message of a synthetic monitor step.

Element Type Description Required
message string

The error message.

 required
code integer

The error code.

 required

The ExternalSyntheticMonitor object

The external synthetic monitor.

Element Type Description Required
id string

The ID of the monitor.

 required
title string

The name of the monitor.

 required
description string

A description of the monitor.

 optional
testSetup string

The information on monitor setup, for example browser.

 optional
expirationTimestamp integer

The timestamp of the monitor expiration, in UTC milliseconds.

 optional
drilldownLink string

The URL to the results of monitor execution.

 optional
editLink string

The URL to edit the monitor in the original UI.

 optional
enabled boolean

The monitor is enabled (true) or disabled (false). Default is true.

If true, set the deleted parameter to false.

 optional
deleted boolean

The flag of the deleted monitor. Default is false.

If true, set the enabled parameter to false.

 optional
locations SyntheticTestLocation[]

Locations from which the synthetic monitor runs.

 optional
steps SyntheticTestStep[]

Steps of the external monitor.

 optional
noDataTimeout integer

The timeout of the monitor, in seconds. If no result is reported within this time, the availability state switches to unmonitored. Default is doubled frequency of the monitor.

 optional
scheduleIntervalInSeconds integer

The frequency of the monitor, in seconds. The monitor is repeated with the specified interval at the external source.

DESK expects results of a monitor execution with the specified interval. If you report results to DESK less often, adjust the noDataTimeout value accordingly.

 required

The SyntheticTestStep object

The step of a synthetic monitor.

Element Type Description Required
id integer

The ID of the step.

 required
title string

The name of the step, displayed in the UI.

 required

The SyntheticTestLocation object

Synthetic test location.

Element Type Description Required
id string

The ID of the location.

 required
enabled boolean

The location is enabled/disabled. Default is true, enabling the location.

 optional

The ExternalSyntheticLocation object

The external Synthetic location.

Element Type Description Required
id string

The ID of the location.

 required
name string

The name of the location, displayed in the UI.

 required
ip string

The IP address of the location.

 optional

Response format

A successful request doesn't return any content.

Example

In this example, the request pushes the following data from external synthetic engine My external synthetic to DESK:

  • Three locations: Linz1, Linz2, and Linz3.
  • Two monitors: example of synthetic monitor - 1 and example of synthetic monitor - 2, each containing three steps and running from two locations.
  • One result per step, per location, for each monitor.

Monitors have the following parameters:

example of synthetic monitor - 1 example of synthetic monitor - 2
Frequency 300 seconds (5 minutes) 300 seconds (5 minutes)
Locations Linz1
Linz2		 Linz2
Linz3
Steps Step1-1
Step1-2
Step1-3		 Step2-1
Step2-2
Step3-3

The example of synthetic monitor - 1 monitor has the following response times in milliseconds:

Linz1 Linz2
Step1-1 7790 2075
Step1-2 2073 4079
Step1-3 8650 3937

The example of synthetic monitor - 2 monitor has the following response times in milliseconds:

Linz2 Linz3
Step2-1 2200 9123
Step2-2 6903 9722
Step2-3 4821 1717

The API token is passed in the Authorization header.

Since the request body is lengthy, it is truncated in this example Curl section. See the full body in the Request body section. You can download the request body JSON to perform a sample request in your environment. Be sure to replace the time stamps with recent ones or the results will be too old.

Curl

curl -X POST \
  https://mySampleEnv.live.dexp.ae/api/v1/synthetic/ext/tests \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \  
  -d '{ <truncated - see the Request body section >}'

Request URL

https://mySampleEnv.live.dexp.ae/api/v1/synthetic/ext/tests

Request body

api-examples/synthetic/post-ext-monitor.json
Download 
{
  "syntheticEngineName": "My external synthetic",
  "syntheticEngineIconUrl": "https://static.thenounproject.com/png/1745-200.png",
  "messageTimestamp": 1543572265528,
  "locations": [
    {
      "id": "Linz1",
      "ip": "127.0.0.1",
      "name": "Linz1"
    },
    {
      "id": "Linz2",
      "ip": "127.0.0.2",
      "name": "Linz2"
    },
    {
      "id": "Linz3",
      "ip": "127.0.0.3",
      "name": "Linz3"
    }
  ],
  "tests":
  [
    {
      "id": "externalSynteticMonitor1",
      "title": "example of synthetic monitor - 1",
      "scheduleIntervalInSeconds": 300,
      "locations":
      [
        {
          "id": "Linz1"
        },
        {
          "id": "Linz2"
        }
      ],
      "steps": [
        {
          "id": 1,
          "title": "Step1-1"
        },
        {
          "id": 2,
          "title": "Step1-2"
        },
        {
          "id": 3,
          "title": "Step1-3"
        }
      ]
    },
    {
      "id": "externalSynteticMonitor2",
      "title": "example of synthetic monitor - 2",
      "scheduleIntervalInSeconds": 300,
      "locations": [
        {
          "id": "Linz2"
        },
        {
          "id": "Linz3"
        }
      ],
      "steps": [
        {
          "id": 1,
          "title": "Step2-1"
        },
        {
          "id": 2,
          "title": "Step2-2"
        },
        {
          "id": 3,
          "title": "Step2-3"
        }
      ]
    }
  ],
  "testResults": [
    {
      "id": "externalSynteticMonitor1",
      "totalStepCount": 3,
      "locationResults": [
        {
          "id": "Linz1",
          "startTimestamp": 1543572262538,
          "success": true,
          "stepResults": [
            {
              "id": 1,
              "startTimestamp": 1543572262538,
              "responseTimeMillis": 7790
            },
            {
              "id": 2,
              "startTimestamp": 1543572262538,
              "responseTimeMillis": 2073
            },
            {
              "id": 3,
              "startTimestamp": 1543572262538,
              "responseTimeMillis": 8650
            }
          ]
        },
        {
          "id": "Linz2",
          "startTimestamp": 1543572262548,
          "success": true,
          "stepResults": [
            {
              "id": 1,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 2075
            },
            {
              "id": 2,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 4079
            },
            {
              "id": 3,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 3937
            }
          ]
        }
      ]
    },
    {
      "id": "externalSynteticMonitor2",
      "totalStepCount": 3,
      "locationResults": [
        {
          "id": "Linz2",
          "startTimestamp": 1543572262548,
          "success": true,
          "stepResults": [
            {
              "id": 1,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 2200
            },
            {
              "id": 2,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 6903
            },
            {
              "id": 3,
              "startTimestamp": 1543572262548,
              "responseTimeMillis": 4821
            }
          ]
        },
        {
          "id": "Linz3",
          "startTimestamp": 1543572262558,
          "success": true,
          "stepResults": [
            {
              "id": 1,
              "startTimestamp": 1543572262558,
              "responseTimeMillis": 9123
            },
            {
              "id": 2,
              "startTimestamp": 1543572262558,
              "responseTimeMillis": 9722
            },
            {
              "id": 3,
              "startTimestamp": 1543572262558,
              "responseTimeMillis": 1717
            }
          ]
        }
      ]
    }
  ]
}

Response code

204

Result

Highlight shows parameters, submitted in the request.

External synthetic monitorsExternal synthetic monitor details