Cloud Data APIs

Data APIs refer to visualization of analytic data.

Rollups (aka Dashboards)

Fetch

GET /:partner/:org/view/rollup/:rollup

{
  "sceneFilter": [
    "part/org/view/scene/2ca4c01db9623076cb80e7810cf7938c4b4f7d4e"
  ],
  "dateModified": "2017-02-01T08:48:35Z",
  "components": [
    "name",
    "experience",
    "impairments",
    "events",
    "health",
    "navigation"
  ],
  "healthDefinitions": [
    20,
    60
  ],
  "eventing": false,
  "resourceVersion": "2",
  "dateCreated": "2017-02-01T08:48:33Z",
  "rollupName": "myrollup",
  "pqType": "hour",
  "status": {
    "state": "complete",
    "reasons": []
  }
}

rollupName : string 1 – 50 character display name for this rollup.

components : A list of columns to display on the dashboard – only "name" is required. Possible values are "name", "health", "experience", "impairments", "events", "navigation".

eventing : true | false - determines whether PQ events are used for all the Scenes in the rollup

pqEventSpec : Specifies the criteria for triggering events. Mandatory it eventing=true.

• pqScore : 0-100. If the PQ scores drop below this level, an event is triggered.

• breaches : 1-15. Determines how many scores below pqScore are required to trigger the event. Must not be bigger than sampleSize.

• sampleSize : 1-15. Determines the number of consecutive PQ scores used when considering events.

email : true | false – Flag indicating if there are currently subscribers to this rollup's email schedule.

• emailSchedule : an email schedule can either by weekly, monthly by day, or monthly by date, and must also be given a timezone.

• timezone : Timezone string for this schedule.

• weeklySchedule : a list of [ :dayOfWeek, :hour, :min ] values. Example below meaning 1st day (1: Monday, 7: Sunday), 2nd hour, 0th minute.

  [1, 2, 0]

• monthlyScheduleByDay : an object of keys to values for the week, day, hour, and min (minute) to schedule events.

  {
    "week": 1,
    "day": 1,
    "hour": 2,
    "min": 0
  }

• monthlyScheduleByDate : an object of keys to values for a specific date in each month, hour, and min (minute) schedule events.

  {
    "date": 1,
    "hour": 2,
    "min": 0
  }

pqType : string enum which defines the timeframe over which scores are displayed – "minute", "hour", "day", "week", "month" NB: minute and hour are fast numbers and return results slightly differently

sceneFilter : list of scenes uris visible on this rollup

sortOrder : struct defining the column to sort and the direction, where the column is one of the following: name, health, meanPQ, physicsPQ, impairments, events

• nameFilter : string filter on scene name

• healthFilter : list of 3 booleans, where first is to show ✓s, 2nd to show ‒s, and 3rd to show 𝖷s

• meanPQFilter : list of lists defining bounds for values in the meanPQ component. The following would only show scores from 0-30 and from 70-100
[ [ 0, 30 ], [ 70, 100 ] ]

• physicsPQFilter : same as meanPQFilter, but on the physicsPQ component

• impairmentFilter : string filter on impairment bucket names

• eventsFilter : list of 2 booleans, where first is to show open events and the second is to show closed events

healthDefinitions : list of 2 numbers representing the lower and upper bounds for 𝖷, ‒, and ✓ in the health column component.

state : todo means being processed,

• complete means that it is Up-to-date,

• warning means no analytics or no rows,

• error means that the included Query would have resulted in too many rows or too many agent-target pairs per row

reasons : Empty when state is not error or warning, otherwise a list of ZERO_ROWS, ZERO_ANALYTICS, ROW_LIMIT_EXCEEDED, ROW_ANALYTICS_LIMIT_EXCEEDED

Scenes

GET /:partner/:org/view/rollup/:rollup/scenes

{
  "scenes": [
    {
      "sceneUri": "suzu1/sz1001/view/scene/4488040dd5d7471bb66a9211d3a8b79baa5dda60",
      "name": "MyScene UK Bristol"
    }
  ]
}

Scene Details

GET /:partner/:org/view/rollup/:rollup/scene_details

To save requesting the (Scenes API)[#scenes] for ever scene listed via (Rollup Scenes)[#scenes-get-partnerorgviewrolluprollupscenes] these details can all be returned in one go via the scene_details API.

{
  "scenes": [
    {
      "sceneUri": "suzu1/sz1001/view/scene/4488040dd5d7471bb66a9211d3a8b79baa5dda60",
      "missionUri": "suzu1/sz1001/mission/szk-mm1",
      "name": "MyScene UK Bristol"
    }
  ]
}

Fetch Results

GET /:partner/:org/view/rollup/:rollup/results

[
  {
    "u": "part/org/view/scene/3c4f2e3a363d68075aebb14d76465129fd0d2b1f",
    "ex": {
      "phy": 80.6,
      "d": 79.5,
      "w": 45,
      "m": 47.3,
      "c": 45
    },
    "im": {
      "d":["BT",0.1, "BT-Wifi/LAN",0.0],
      "w":["BT",0.0, "BT-Wifi/LAN",0.0],
      "m":["BT",0.0, "BT-Wifi/LAN",0.0],
      "c":["BT",0.0, "BT-Wifi/LAN",0.0]
    },
    "ev": [
      {
        "eu": "part/org/view/scene/3c4f2e3a363d68075aebb14d76465129fd0d2b1f/event_spec/001485955770032944",
        "eo": "2017-02-01T14:00:00Z",
        "ec": "2017-02-01T15:00:00Z",
        "details": {
          "alertPercentage": 60,
          "alertingAnalytics": 15,
          "activeAnalytics": 19,
          "inactiveAnalytics": 1,
          "closedReason": "EV_COND_NOT_MET"
        }
      }
    ],
    "f": {
      "lm": [43.4, "2017-02-01T23:56:00Z"],
      "lh": [43.4, "2017-02-01T20:00:00Z"]
    },
    "t": "up",
    "cc": "insAb",
    "n": 2
  }
]

u : Scene URI for this specific set of results.

ex : Object for periodic batch quality scores.

• phy : physicsPQ score i.e. the best possible score or -1 if not yet available.

• d : score for the day or -1 if not yet available.

• w : score for the week or -1 if not yet available.

• m : score for the month or -1 if not yet available.

• c : score over the associated mission's correlation interval amount of time or -1 if not yet available.

im : Object for impairments for periodic batch quality scores. For each time period (last day, last week, last month) the two largest contributing factors to a scene's score. Could be the router, a particular link etc. Provided in order, biggest first. Always a list of 4 items representing these 2 impairments [<primary-impairment>, <score>, <secondary-impairment>, <score>].
Scores are 0.0 - 1.0.

• d : impairments list for the day.

• w : impairments list for the week.

• m : impairments list for the month.

• c : impairments list over the associated mission's correlation interval amount of time.

ev : list of recently opened events and optionally still-open events.

• eu : required Event URI of the event in question.

• eo : required ISO 8601 date the event was opened.

• ec : optional ISO 8601 date the event was closed.

f : Object for quality scores for real-time numbers, i.e. those for pqType minute and hour. Each item contains the score then a timestamp indicating the time the score was received.

• lm : require list of length 2 for minute score [<score>, <date-time>] or [-1, -1] when no results are not yet available, or [-2, -2] in case the mission is not active.

  [
    43.4,
    "2017-02-01T23:56:00Z"
  ]

• lh : require list of length 2 for hour score [<score>, <date-time>] or [-1, -1] when no results are not yet available, or [-2, -2] in case the mission is not active.

  [
    43.4,
    "2017-02-01T20:00:00Z"
  ]

t : String value describing the rate-of-change for this scene i.e. trending "up", trending "down", or is stable "none".

cc : "exNorm" | "perfNorm" | "insNorm" | "impNorm" | "exAb" | "perfAb" | "insAb" | "impAb"
Cell classification – Since all scenes for a dashboard are delivered at once this value provides the value to filter on when drilling down from the dashboard to the scene list normally used on mobile device views

n : Number of analytics in the scene.

Shared Users

GET /:partner/:org/view/rollup/:rollup/shared

Users that require explicit sharing (i.e. Role user_role/basic%20viewer) are shared Rollups directly via this API.

{
  "userUris": [
    "ae/org1/user/e2c5defbd7d7667590e5745e0b952f0daae4dc5b"
  ]
}

Update Shared Users

PUT /:partner/:org/view/rollup/:rollup/shared

{
  "addUserUris": [],
  "removeUserUris": [
    "ae/org1/user/e2c5defbd7d7667590e5745e0b952f0daae4dc5b"
  ],
  "sharedWith": []
}

• addUserUris optional : a list of user uris to share this rollup with

• removeUserUris optional : a list of user uris to remove from the share list for this rollup

Subscriptions

Rollup subscriptions are handled by the Subscriptions API with :resource view/rollup/:rollup.

Rollup Latest Changes

This API allows listing of all the rollups that have been modified after a given time.

List

GET /:partner/:org/view/rollup/_changes?since=Since

since : A time in ISO8601 format, for an example "2018-01-14T12:30:45Z"

[
  {
    "rollupUri": "p2/org1/view/rollup/001538385436913957",
    "status": {
      "reasons": [],
      "state": "complete"
    },
    "dateModified": "2018-10-01T09:17:39Z"
  }
]

The contents of the LIST response has exactly the same format at LIST rollups.

Scenes

New scenes are created via the rollups update scenes uri, at which time a sceneUri field is returned that matches the uri syntax within this section.

List

GET /:partner/:org/view/scene

{
  "scenes": [
    {
      "sceneUri": "suzu1/sz1001/view/scene/4488040dd5d7471bb66a9211d3a8b79baa5dda60",
      "rollupUri": "suzu1/sz1001/view/rollup/001536242004760047",
      "missionUri": "suzu1/sz1001/mission/szk-mm1",
      "name": "Suzuki-Scene14949"
    }
  ]
}

Fetch

GET /:partner/:org/view/scene/:scene

{
  "resourceVersion": "3",
  "dateCreated": "2018-09-06T13:53:45Z",
  "missionUri": "p1/org1/mission/mission1",
  "name": "my-scene Unknown"
}

Events

List Definitions

GET /:partner/:org/view/scene/:scene/events

{
  "dateModified": "2018-09-06T13:53:45Z",
  "pqEventSpecs": [
    {
      "eventUri": "p1/org1/view/rollup/001536242004760047/event_spec",
      "sampleSize": 2,
      "pqScore": 75,
      "breaches": 1,
      "granularity": "mmi"
    }
  ],
  "resourceVersion": "3",
  "dateCreated": "2018-09-06T13:53:45Z"
}

Update Definition

PUT /:partner/:org/view/scene/:scene/events

{
  "pqEventSpecs": [
    {
      "eventUri": "asd/sz1001/view/scene/a58ffdcfc655e7b701eacce97b4d17068cb013dd/event_spec/001506951676646707",
      "granularity": "mmi",
      "pqScore": 75,
      "sampleSize": 4,
      "breaches": 2
    }
  ]
}

• eventUri : optional The URI of the event may also be modified

• granularity : optional "mmi" meaning instant scores (only allowed value, kept for backward compatibility)

• pqScore : required 0.0-100.0 the threshold value for the event

• sampleSize : required 1-10 The number of consecutive scores to be considered

• breaches : required 1-10 Must not be bigger than 'sampleSize' The number of scores below the 'pqScore' before triggering an event

Response

{
  "dateModified": "2017-10-02T13:48:52Z"
}

Query PQ Events

GET /:partner/:org/view/scene/:scene/pq_events

Query opened/closed events in a time window based on the above event definitions.

This API is versioned: - v1 only returns old-style events; new-style events are filtered out for backwards compatibility - v2 returns both old-style and new-style events, see below.

Example query string:

?sd=2018-01-30T00:00:00Z&ed=2018-01-30T12:30:00Z

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 92 days.

• ed : ISO 8601 query end date.

[
  {
    "event": {
      "pqScore": 50,
      "granularity": "hour",
      "breaches": 1,
      "sampleSize": 1
    },
    "eventUri": "ae/org1/view/scene/aac0e1c16900b260e761824247b8c6bf508d401e/event_spec/001486383427143354",
    "open": 738000000
  },
  {
      "eventUri": "ae/org1/view/scene/:sceneid/event/:eventId",
      "open": 738000000,
      "closed": 738500000,
      "event": {
        "alertPercentage": 20,
        "alertingAnalytics": 15,
        "activeAnalytics": 20,
        "inactiveAnalytics": 1,
        "closedReason": "EV_COND_NOT_MET"
      }
    }
]

• event : required The definition of the event. New-style events are defined by the following fields: alerPercentage, alertingAnalytics, activeAnalytics, inactiveAnalytics, closedReason. Old-style event definitions are unchanged.

• eventUri : required URI to the above mentioned event resource.

• open : required delta timestamp in milliseconds from sd (can be < sd, i.e. negative stating the event opened before the query window)

• closed : optional delta timestamp in milliseconds from sd (can be > ed when the event closed after the query window)

Event Details

GET /:partner/:org/view/scene/:scene/event/:eventId

Scene events are now resources that can be directly accessed given a unique URI.

The following details are returned for an event: * the open / closed timestamps * the number of alerting, active and inactive analytics that contributed to the event * the accumulated blame counts for the analytics in the scene * the alertPercentage at the time the event was opened * if the event was closed, a reason is provided as well. For e.g. "EV_COND_NOT_MET", "EV_ALERT_PERCENTAGE_CHANGED", "EV_NO_ACTIVE_ANALYTICS", "EV_DEF_REMOVED".

{
    "open": 738000000,
    "closed": 738500000,
    "alertPercentage": 20,
    "alertingAnalytics": 15,
    "activeAnalytics": 20,
    "inactiveAnalytics": 1,
    "closedReason": "EV_COND_NOT_MET"
  }

Event Barchart

GET /:partner/:org/view/scene/:scene/event/:eventId/barchart

Returns the number of analytics in each state (alerting, active, inactive), over the course of an event. For events that lasted for more than 24h, the barchart list is returned per day.

[
  {
    "time": "<time_delta>",
    "alertingAnalytics": 6,
    "activeAnalytics": 8,
    "inactiveAnalytics": 10
  },
  ...
]

Event Contributing Analytics

GET /:partner/:org/view/scene/:scene/event/:eventId/analytics

This API returns the list of relevant analytics for an event, the reason for their relevance, the latest state and blame.

[
 {
   "agent": "<agentId>",
   "target": "<targetId>",
   "state": "ALERTING" | "INACTIVE" | "ACTIVE",
   "latestAlertingPhaseUri": "<phaseUri>" | null,
   "everAlerted": true | false,
   "everInactive": true | false
 },
 …
]

Fetch Mission

GET /:partner/:org/view/scene/:scene/mission

Fetch a scene's associated Mission with limited fields returned.

{
  "intervalFactor": 4,
  "timezone": "UTC",
  "displayName": "mymissionf",
  "missionId": "mymissionf",
  "missionUri": "ae/org1/mission/mymissionf",
  "defaultSupplier": "mission default",
  "pqEventThreshold": 60
}

Agents

GET /:partner/:org/view/scene/:scene/agents

Fetch a scene's associated agents/targets.

{
  "agents": [
    {
      "targets": [
        {
          "targetId": "mytarget",
          "displayName": "mytarget",
          "targetUri": "ae/org1/target/mytarget",
          "description": "Agent Bristol_234",
          "useTimerForAppRtt": 0,
          "networkMeasurementsToCloudProxy": false
        }
      ],
      "displayName": "cdug1 1",
      "properties": {
          "hostname": "1",
          "city": "cdug1"
      },
      "agentId": "10e6bebdd18e95d624ab3922bc96fdf49d40002b",
      "unresolved": "no group matched",
      "agentUri": "p1/org1/agent/10e6bebdd18e95d624ab3922bc96fdf49d40002b",
      "agentVersion": "4.3.0.0",
      "agentDescription": "cdug1_1",
      "agentType": "desktop",
      "service": "Suzuki ISP",
      "reference": "Windows 15.77",
      "dateCreated": "2018-09-06T13:53:26Z",
      "dateModified": "2018-09-06T13:53:26Z"
    }
  ]
}

Fields defined via Agent and Target APIs.

• unresolved : Only included when agent was not resolved into a Base agent group. Otherwise the field baseAgentGroupUri is included.

• displayName : Only provided when the agent has a display name. Meaning there is at least one agentDisplayname property associated with a value

Rollups

GET /:partner/:org/view/scene/:scene/rollups

{
  "rollups": [
    "ae/org1/view/rollup/001486383424399812"
  ]
}

• rollups : A list of Rollup URIs.

Headline

GET /:partner/:org/view/scene/:scene/headline

A summary of score windows for a scene, plus the latest event details on the scene and the fast numbers results (for a scene on a fast rollup).

{
  "name": "scene1",
  "ex": {
    "phy": 80.6,
    "d": 43.4,
    "w": 40.3,
    "m": 47,
    "c": 40.3
  },
  "results": {
    "ev": [
      {
        "eu": "/:partner/:org/view/scene/:scene/event/:eventId",
        "eo": "2017-02-01T14:00:00Z",
        "ec": "2017-02-01T14:00:00Z",
        "details": {
          "alertPercentage": 60,
          "alertingAnalytics": 15,
          "activeAnalytics": 19,
          "inactiveAnalytics": 1,
          "closedReason": "EV_COND_NOT_MET"
        }
      }
    ],
    "f": {
      "lm": [43.4, "2017-02-01T23:56:00Z"],
      "lh": [43.4, "2017-02-01T20:00:00Z"]
    }
  }
}

ex : Object for periodic batch quality scores.

• phy : physicsPQ score i.e. the best possible score or -1 if not yet available.

• d : score for the day or -1 if not yet available.

• w : score for the week or -1 if not yet available.

• m : score for the month or -1 if not yet available.

• c : score over the associated mission's correlation interval amount of time or -1 if not yet available.

Timescale

GET /:partner/:org/view/scene/:scene/timescale

Returns a series of mean, max, and min scores across a time window with specific granularity. Useful for display graphs of scores over time.

Example query string: : ?sd=2018-01-30T00:00:00Z&ed=2018-01-30T12:30:00Z&gr=hour

The following query string arguments are required:

• sd : ISO 8601 query start date.

• ed : ISO 8601 query end date.

• gr : "instant" | "hour" | "day" | "week" | "month" query granularity.
  Max difference in days between sd and ed cannot exceed:

  "instant" 1 day
  "hour" 31 days
  "day" 92 days
  "week" 366 days
  "month" 366 days

[
  {
    "mean": 43.6,
    "max": 81.8,
    "min": 1.7,
    "time": 31241341000
  },
  {
    "mean": 7.6,
    "max": 7.6,
    "min": 7.6,
    "time": 30636541000
  }
]

• mean : Mean score over time window granularity starting at time

• max : Max score over time window granularity starting at time

• min : Min score over time window granularity starting at time

• time : Delta timestamp from requested sd in milliseconds

Bar Chart

GET /:partner/:org/view/scene/:scene/pq_barchart

Reports on a scene whereby each integerPQ value represents the percentage of scores seen at that index where the index is the integer score value. e.g. the 80th element's value is 99.7 meaning 99.7% of scores fell 79.5 >= score < 80.5.

Example query string:

?sd=2018-01-30T00:00:00Z&ed=2018-01-30T12:30:00Z

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 92 days.

• ed : ISO 8601 query end date.

{
  "integerPQ" : [
    0,
    ...,
    0,
    0.3,
    0,
    99.7,
    0,
    0,
    ...
  ],
  "excellent": 0,
  "good": 100,
  "fair": 0,
  "poor": 0,
  "bad": 0
}

• integerPQ : 100 length list of floats representing percentage of scores falling at this score by index. e.g. 80th element represents count of scores falling in range 79.5 >= score < 80.5.

• excellent : Percentage of scores classified as excellent.

• good : Percentage of scores classified as good.

• fair : Percentage of scores classified as fair.

• poor : Percentage of scores classified as poor.

• bad : Percentage of scores classified as bad.

Impairment

GET /:partner/:org/view/scene/:scene/impairment

Example query string:

?sd=2018-01-30T00:00:00Z&ed=2018-01-30T12:30:00Z&ni=8&g=1&gti=1

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 31 days.

• ed : ISO 8601 query end date.

• ni : 1 – 8 number of impairments per group

[
  {
    "impairments": [
      {
        "breakdown": [
          {
            "severity": 13.7,
            "asn": 12345,
            "supplier": "Other"
          }
        ],
        "severity": 13.7,
        "supplier": "Other",
        "asn": 12346,
        "type": "ip",
        "ip": "10.0.0.2",
        "mapping": ["abc.co.uk", "abc.com", "abc hosts"],
        "time": "2017-02-07T13:08:49Z",
        "index": 1,
        "analytics": [
                 { "agentId": "asdjklajaskled", "targetId": "dsjkfaljsklfdsjakl" },
                 { "agentId": "asdjklajaskled", "targetId": "dsjkfaljsklfdsjakl" },
               ]
      }
    ],
    "time": "2017-02-07T13:08:49Z"
  }
]

• breakdown : List of suppliers contributing to total severity of impairment source.

• severity : Weighting of impairment

• supplier : Supplier "bucket" containing this impairment

• type : "all" | "ip" | "application" | "network"

• ip : IP address or subnet of an impairment, unless type is "all" in which case a targetUri will be supplied.

• mapping : If there is mapping defined for the ip and the type is "ip" we return the mappings associated with the IP.

• time : Time at which impairment was captured.

• index : Position of impairment in stack, lower number means bigger impairment.

• analytics : List of top 8 analytics that blame each network impairment

• asn : Autonomous System Numbers

Impairment Analytics

POST /:partner/:org/view/scene/:sceneId/impairment_analytics

This API returns the behaviour of the requested analytics if it can be determined.

{
 "ip": "1.2.3.4",
 "startDate": "ISO8601",
 "endDate": "ISO8601",
 "analytics": [
   {
     "agentId": "<agentId>",
     "targetId": "<targetId>"
   },
   // ...
 ]
}

• ip : A valid IPV4 or CIDR address mandatory

• analytics : A list of valid agent target pairs.

• startDate : ISO 8601 date. Max range between startDAte and endDate is 31 days.

• endDate : ISO 8601 date.

Response

{
 "analytics": [
   {
     "agentId": "asjkflsajklfsjdaklfjasdkl",
     "targetId": "dsajkfl",
     "behaviour": "LOSS",
     "weight": 12.1
   },
   {
     "agentId": "zxcvmzxvnmiopsafizxviopfo",
     "targetId": "zxvzxcv",
     "behaviour": "DELAY",
     "weight": 18.2
   },
   // ...
 ]
}

Scatter Plot

GET /:partner/:org/view/scene/:scene/scatter

Example query string:

?sd=2018-01-30T00:00:00Z&ed=2018-01-30T12:30:00Z&type=ip&ip=169.10.0.1

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 31 days.

• ed : ISO 8601 query end date.

• type : "ip" | "network" | "application" | "all"

• ip : IP address in the form a.b.c.d, or subnet in the form a.b.c.d/z to filter by only when "type": "ip" otherwise a target ID.

{
  "fair": [
    [
      100,
      0
    ]
  ],
  "good": [
    [
      100,
      0
    ],
    [
      100,
      0
    ],
    [
      100,
      0
    ]
  ]
}

• excellent : optional List of [X,Y] values for this classification's end-to-end quality scores

• good : optional List of [X,Y] values for this classification's end-to-end quality scores

• fair : optional List of [X,Y] values for this classification's end-to-end quality scores

• poor : optional List of [X,Y] values for this classification's end-to-end quality scores

• bad : optional List of [X,Y] values for this classification's end-to-end quality scores

Supply Chain History

POST /:partner/:org/view/scene/:scene/supply_chain_history

This report differs from others above in that it accepts a POST request.

{
  "sd": "2017-02-01T16:10:30Z",
  "ed": "2017-02-08T16:10:30Z",
  "agents": [
    "eb4c20a80ea9d9ab20f531255262e5f4ba77258d"
  ],
  "all": false
}

• sd : required ISO 8601 query start date. Max range between sd and ed is 31 days.

• ed : required ISO 8601 query end date.

• agents : optional A list of Agent IDs

• all : optional true | false whether to report on all agents – if not-supplied or false the agents list must be specified.

Response

{
     "all": {
          "maxPQ": 80.579634,
          "mspPQ": -1,
          "meanPQ": 43.643296,
          "weight": 17088,
          "buckets": [
               {
                    "buket": "Server",
                    "asn": null,
                    "blame": 0
               },
               {
                    "bucket": "Server (Application)",
                    "asn": null,
                    "blame": 0
               },
               {
                    "bucket": "Other",
                    "asn": 1234,
                    "blame": 0
               },
               {
                    "bucket": "Server (Network)",
                    "asn": 1234,
                    "blame": 0
               }
          ]
     },
     "ats": [
          {
               "agentId": "eb4c20a80ea9d9ab20f531255262e5f4ba77258d",
               "targetId": "mytarget",
               "maxPQ": 80.579634,
               "mspPQ": -1,
               "meanPQ": 43.643296,
               "weight": 17088,
               "buckets": [
                    {
                         "bucket": "Server (Network)",
                         "asn": 1234,
                         "from": {
                              "bucket": "Supplier 1",
                              "asn": 1234
                         }
                    },
                    "blame"
                    :
                    0
                    },
                    {
                         "bucket": "Other",
                         "asn": 1234,
                         "blame": 0
                    },
                    {
                         "bucket": "Server (Application)",
                         "asn": 1234,
                         "blame": 0
                    },
                    {
                         "bucket": "Server",
                         "asn": 1234,
                         "blame": 0
                    }
               ]
          }
     ]
}

all : Object containing average values for requested Agent/Targets, which contains the same keys as a single A/T supply chain (albeit without targetId).

ats : List of Agent/Target pairs

• agentId : Agent's id

• targetId : Target's id.

• maxPQ : The potential quality score for the Agent/Target pair over the requested time period.

• meanPQ : This is the mean quality score for the A/T over the requested time period.

• weight : Weighting of quality score for use in calculating mean quality score for average row.

• buckets : List of suppliers in the supply chain.

• supplier : name of the supplier.

• blame : the relative blame of this supplier in the supply chain.

• from : optional for peer to peer supplier info

Agents

Raw Measurement Data

GET /:partner/:org/view/agent/:agent/raw

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 31 days.

• ed : ISO 8601 query end date.

• tgt : A Target id the agent has been associated.

{
  "m": [
    {
      "e": ["192.168.0.1", true, 0, "192.168.0.1", "192.168.0.1"],
      "d": [
        ["10.0.0.1", 1, 100, 1, 0, 100, 100, 100, 0],
        ["10.0.0.2", 2, 100, 1, 0, 100, 100, 100, 0]
      ],
      "p": [0.25, 1, 0, 0.25, 0.25, 0.25, 0],
      "t": 121000
    },
    ...
  ]
}

• m : A list of Measurements as submitted by the Digital User/Agent. All fields are the same except "t" which is rewritten to be in milliseconds relative to query variable sd.

• t : Delta timestamp - milliseconds elapsed since sd query value.

Scores

GET /:partner/:org/view/agent/:agent/pq

The following query string arguments are required:

• sd : ISO 8601 query start date. Max range between sd and ed is 7 days.

• ed : ISO 8601 query end date.

• tgt : A Target id the agent has been associated.

• m : A Mission URI used for analysis of the above agent/target raw measurements.

[
  {
    "pq": 43.4,
    "t": 83000
  },
  {
    "pq": 43.4,
    "t": 323000
  },
  {
    "pq": 43.4,
    "t": 563000
  },
  {
    "pq": 43.4,
    "t": 803000
  }
  ...
]

• pq : 0.0 – 100.0 Scores

• t : Delta timestamp - milliseconds elapsed since sd query value.

Auto-diagnosis (blame) chart

POST /:partner/:organisation/view/agent/:agent/blame

{
  "m": "ae/test0/mission/RHS-MIS-1",
  "tgt": "RHS-DT-1",
  "sd": "2018-11-20T03:53:24Z",
  "ed": "2018-11-20T15:53:24Z",
  "ev": {
    "sampleSize": 5,
    "breaches": 4,
    "granularity": "mmi",
    "pqScore": 70.0
  }
}

• m : required A Mission URI

• tgt : required A Target id the agent has been associated.

• sd : required ISO 8601 query start date.

• ed : required ISO 8601 query end date. Max range between sd and ed is 1 day.

Response

The analytic is not alerting.

HTTP/1.1 200 OK
{
  "alerting": false
}

The analytic is alerting, but there is not enough data do perform the analysis.

HTTP/1.1 200 OK
{
  "alerting": true,
  "sufficientDataPoints": false
}

The analytic is alerting and there is enough data to perform the analysis and increase the corresponding counters.

HTTP/1.1 200 OK
{
  "alerting": true,
  "sufficientDataPoints": true,
  "netCongestionCounter": 2,
  "netCongestionWithTimeoutCounter": 1,
  "appCongestionCounter": 3,
  "timeoutCounter": 3,
  "httpCodes500": {
    "500": 1,
    "502": 3
  },
  "httpCodes400": {
    "400": 1
  },
  "netAppCongestionCounter": 2,
  "chronicNetCongestionCounter": 1,
  "chronicAppCongestionCounter": 1,
  "totalScores": 10,
  "totalScoresBeneathThreshold": 7,
  "netType": 2,
  "fastBlameState": "net"
}

• fastBlameState : what is to blame the most: the network (net), the application (app), both (both) or inconclusive (unknown).

DU Supplier Routes

POST /:partner/:organisation/view/agent/:agent/supplier_route

Retrieve the ordered suppliers list derived from the underlying network paths for the analytic.

{
  "m": "ae/test0/mission/RHS-MIS-1",
  "tgt": "RHS-DT-1",
  "sd": "2018-11-20T03:53:24Z",
  "ed": "2018-11-20T15:53:24Z"
}

• m : required A Mission URI

• tgt : required A Target id the agent has been associated.

• sd : required ISO 8601 query start date.

• ed : required ISO 8601 query end date. Max range between sd and ed is 31 days.

Response

{
  "supplierRoutes": [
 ["LAN", "Virgin", "Level3", "DC"],
 ["LAN", "Virgin", "_Unknown", "Level3", "DC"],
 ["LAN", "Virgin", "_Unknown", "Level3", "_Unknown", "DC"],
 ["LAN", "Virgin", "Other", "Level3", "DC"],
 ["LAN", "Virgin", "Other", "Level3", "Other", "Level3", "DC"]
   ],
  "suppliers": [
       {
            "name": "Virgin",
            "asn": 1234
       }
  ]
}

Agent Timescale

GET /:partner/:organisation/view/agent/:agentId/timescale?gr=<granularity>&tgt=<targetId>&m=<missionId>

Retrieve the quality history graph on an analytic context.

• m : required A Mission id

• tgt : required A Target id the agent has been associated.

• sd : optional ISO 8601 query start date.

• ed : optional ISO 8601 query end date.

• gr : required Granularity: one of instant, hour, day, according to the duration in which the analytic were derived

Notes:

• startDate and endDate parameters are optional; if not supplied, the AC will compute the start date and end date using the granularity.
• Go back from now to the mission midnight. This is endDate.

• startDate is then computed using the granularity:

  • For instant: startDate = endDate - 1 day in seconds
  • For hour: startDate = endDate - 7 days in seconds
  • For day: startDate = endDate - 31 days in seconds
  • For week: startDate = endDate - 92 days in seconds
  • For month: startDate = endDate - 366 days in seconds

• If supplied, both startDate and endDate must be set (you can’t supply one without the other).

Response

{
    "missionTimezone": "UTC",
    "intervalFactor": 4,
    "startDate":"2019-04-02T00:00:00Z",
    "scores":
        [
             {
                  "timely": false,
                  "mean": 73.9,
                  "max": 73.9,
                  "min": 73.9,
                  "time": 120000
             },
             {
                  "timely": true,
                  "mean": 71.9,
                  "max": 71.9,
                  "min": 71.9,
                  "time": 360000
             }
        ]
}

Agent phases

POST /:partner/:organisation/view/agent/:agentId/phase

Retrieve agent phases in the given time window.

{
  "m": "ae/test0/mission/RHS-MIS-1",
  "tgt": "RHS-DT-1",
  "sd": "2018-11-20T03:53:24Z",
  "ed": "2018-11-20T15:53:24Z"
}

• m : required A Mission URI

• tgt : required A Target id the agent has been associated.

• sd : required ISO 8601 query start date.

• ed : required ISO 8601 query end date. Max range between sd and ed is 24 hours.

Response

[
  {
   "phaseUri": "ae/org1/view/agent/:agentId/phase/:id",
   "open": 738000000,
   "closed": 738500000,
   "state": "ALERTING_APP"
 },
 {
   "open": 1283901839021890,
   "closed": 238940238409283940,
   "state": "INACTIVE"
 },
{
   "phaseUri": "ae/org1/view/analytic/:analytic/phase/:id",
   "open": 1283901839021890,
   "closed": 238940238409283940,
   "state": "ALERTING"

 },
 {
   "phaseUri": "ae/org1/view/analytic/:analytic/phase/:id",
   "open": 1283901839021890,
   "closed": 238940238409283940,
   "state": "ALERTING"
 }
 …
]

Auto-diagnosis

POST /:partner/:organisation/view/agent/:agent/phase/:phaseId

{
  "m": "ae/test0/mission/RHS-MIS-1",
  "tgt": "RHS-DT-1",
}

• m : required A Mission URI

• tgt : required A Target id the agent has been associated.

Response

The analytic is not alerting.

{
    "startDate": <datetime>,
    "endDate": <datetime>,
    "pqEventThreshold": 75,
    "blame": {
        "sufficientDataPoints": true,

        // blame of the analytic
        "fastBlameState": net | app | both | unknown

        // blame counts
        "blame": {
            "net": <net percentages>;
            "app": <app percentages>;
            "both": <both percentages>
        }

        // detailed analysis - meta (not used by the UI)
        "totalScores": 15,
        "totalScoresBeneathThreshold": 7,

        // http response details
        "timeoutCounter": 3,
        "successCounter": 2,
        "noneCounter": 2,

       "httpCodes500": {
          "500": 1,
          "502": 3
       },
       "httpCodes400": {
          "400": 1
       },
       "httpCodes300": {
          "306": 5
       }
    }
}

• fastBlameState : What is to blame the most: the network (net), the application (app), both (both) or inconclusive (unknown).

• startDate : The delta timestamp between now and when the phase has started.

• endDate : The delta timestamp between now and when the phase has ended.

Agent impairment evidence

POST /:partner/:org/view/agent/:agentId/evidence

{
 "targetId": "sajfklsaj",
 "missionUri": "partner/org/mission/masdkjasl",
 "startDate": "ISO8601",
 "endDate": "ISO8601",
 "ip": "1.2.3.4",
 "behaviour": "LOSS" | "DELAY" | "BOTH"
}

• targetId : required A valid targetId

• ip : required A valid IPV4 or CIDR address

• behaviour : required Enum with one of the following values: "LOSS" | "DELAY" | "BOTH"

• targetId : required A valid targetId

• startDate : required ISO 8601 query start date.

• endDate : required ISO 8601 query end date.

Response

{
  "rtt_no_evidence": boolean(), // no evidence hence no POIs (all points ROUTINE)
  "loss_no_evidence": boolean(), // no evidence hence no POIs (all points ROUTINE)
  "data": [
   {
     "time": "2020-04-08T14:18:00Z",
     "rtt": 0.3123, // seconds - optional when loss is 5 (100%)
     "loss": 2, // count
     "loss_behaviour": "IMPAIRED", // red
     "rtt_behaviour": "TYPICAL", // blue
     "pq": 80.0
   },
  ...
 ]
}

• rtt_no_evidence : A boolean value

• loss_no_evidence : A boolean value

• loss_behaviour : Enum with one of the following values: "IMPAIRED" | "TYPICAL" | "ROUTINE"

• rtt_behaviour : Enum with one of the following values: "IMPAIRED" | "TYPICAL" | "ROUTINE"

• rtt : Float up to 3 decimap points

• time : ISO 8601 date.

• pq : A float. pqis an optional key only applicable to points of interest, i.e. where either loss_behaviour or rtt_behaviour are both is not ROUTINE.

Phase details

GET /:partner/:organisation/view/analytic/:analytic/:phaseId

Retrieve agent phases in the given time window.

Query parameters

• fields : optional all | tooltip

• tgt : required A Target id the agent has been associated.

• sd : required ISO 8601 query start date.

• ed : required ISO 8601 query end date. Max range between sd and ed is 24 hours.

Response

field=all

{
 "startDate": "<iso-datetime>",
 "endDate": "<iso-datetime>",
 "pqEventThreshold": 75,
 "netType": 1,
 "totalTimeoutCount": 15,
 "status": "diagnosed",
 "impairments": [
   {
     "rank": "PRIMARY",
     "cause": "APP_ERROR",
     "location": "<targetId>",
     "details": {
       "errorCodes": [
         {
           "code": 501,
           "count": 21
         },
         {
           "code": 502,
           "count": 13
         },
         {
           "code": 503,
           "count": 6
         }
       ]
     }
   },
   {
     "rank": "SECONDARY",
     // ...
   }
 ]
}

field=tooltip

{
   "startDate": "<iso-datetime>",
   "endDate": "<iso-datetime>",
   "netType": 1,
   "status": "diagnosed",
   "primaryCause": "APP_ERROR"
 }

Phase Supply Chain API

GET /:partner/:organisation/view/analytic/:analytic/phase/:phaseId/supply_chain

Query Params: none

Response

{
 "primaryPath": [
   { "id": 1, "supplier": "Openet", "details": {}, "asn": 12345 },
   { "id": 2, "supplier": "Xerox", "details": {}, "asn": 12346 },
   { "id": 3, "supplier": "AT&T", "details": {}, "asn": 12347 },
   { "id": 4, "supplier": "Private Layer", "details": {}, "asn": 12348 },
   { "id": 5, "supplier": "Xerox", "details": {}, "asn": 12346 },
   { "id": 6, "supplier": "1&1", "details": {}, "asn": 12350 },
   { "id": 7, "supplier": "Superlight", "details": {}, "asn": 12351 },
   { "id": 8, "supplier": "Server", "details": { "target": true }, "asn": null }
 ],
 "pathChange":
   {
     "start": 3,
     "end": 6,
     "path": [
       {"supplier": "Vodafone", "details": {}, "asn": 12341 },
       {"supplier": "Claranet", "details": {}, "asn": 12331 },
       {"supplier": "Ubernet", "details": {}, "asn": 12321 }
     ]
   }
}

• primaryPath : list of nodes that form the primary path

• id : unique identifier for the node

• supplier : the name of the supplier

• details : metadata for the nodes

• target : boolean indicates the target node

• withinSupplier : boolean indicates an “internal” path change. An internal path change is only indicated when there is no external path change. NOTE: In this case the “pathChange” key (see below) will be omitted from the response.

• defaultSupplier : boolean indicates a default mission supplier

• primary : boolean node is the location of the primary diagnosis

• secondary : boolean node is the location of the secondary diagnosis

• primaryDegradedPath : boolean path from this node to the next node is degraded and the primary diagnosis

• secondaryDegradedPath : boolean path from this node to the next node is degraded and the secondary diagnosis

• pathChange : optional description of a detected change in path

• start : the last node (before the path change) on the primaryPath that is also on the “new path”, i.e. the last node before the paths branch

• end : the first node after the path change that is shared between the old and new path (this may be the last node or any other node in the primaryPath), e.g. where the paths converge

• path : list of nodes as described in primaryPath above. It only contains nodes that are not on the primaryPath - and it can be empty as well.

IP Mapping

POST /:partner/:organisation/view/analytic/:analytic/phase/:phaseId/ip_mapping

{
 "location": "10.10.1.0/24"
}

• location : CIDR address

Authorised user role: all user levels are allowed

Response

{
 "mappings": [
   {
     "ip": "10.10.10.1",
     "mapping": [ "Lab1", "Office", /* etc */ ] | null
   },
   // ...
 ]
}

Data exploration

This endpoint provides access to up to 90 days' worth of organisation analytics CSV exports

Request

GET /:partner/:organisation/data_exploration/:yyyy/:mm/:dd
Accept-Encoding: <identity|br|gzip>

Query Params: none

This endpoint supports Content-Encoding compression (Gzip or Brotli) via the optional Accept-Encoding header.

Response

A text stream of type text/csv with filename organisationanalyticdata_<YYYY>-<MM>-<DD>.csv

Request

POST /:partner/:organisation/data_exploration

{
  "geographicRollup": "<rollupUri>",
  "applicationRollup": "<rollupUri>",
  "auditPeriod": "week|month",
  "employees": 10, //1 - 1,000,000,000
  "employeeAnnualCost": 10000, //1 - 1,000,000,000
  "hoursWorked": 8.0, //float: 1.0 - 24.0
}

• geographicRollup : RollupUri where the scene name conforms to Location / Region // Service

• applicationRollup : RollupUri where the scene name conforms to Application / Service

• auditPeriod : Enum with the values of week or month

• employees : Integer between 1 - 1000000000

• employeeAnnualCost : Integer between 1 - 1000000000

• hoursWorked : Float between 1.0 - 24.0

Response

200 Response is a binary stream of type application/zip with a name dashboardanalyticdata_<YYYY>-<MM>-<DD>.zip

Design Export

GET /:partner/:organisation/design/_csv/<entity_type>

Authorised user role: PQ experts and SU.

• entity_types : one of cdug, bdug, spg, target, dug-spg, spg-target

Response

200 Response is a text stream of type

Design Import

POST /:partner/:organisation/design/_csv/<entity_type>

Authorised user role: PQ experts and SU.

• entity_type : one of cdug, bdug, spg, target, dug-spg, spg-target

Response

 { "uploadId": "<uuid>" }