Working with Elements

The following describes all actions that can be executed with or on up.time Elements.

Managing Elements

Listing Elements

List Elements visible to the authenticated user account.

Endpoint

To list all Elements:

GET https://youruptime/api/v1/elements/

To list a specific Element:

GET https://youruptime/api/v1/elements/<id>/

Example Request

List all visible Elements:

GET https://youruptime/api/v1/elements

List a specific Element (e.g., ID #19):

GET https://youruptime/api/v1/elements/19

Example Responses

GET https://youruptime/api/v1/elements/

[
   {
      "description": "My Laptop",
      "groupId": 1,
      "hostname": "win-dleith",
      "id": 1,
      "isMonitored": true,
      "monitors": 
      [
         {
            "elementId": 1,
            "id": 3,
            "isHidden": true,
            "isMonitored": true,
            "name": "Platform Performance Gatherer"
         },
         {
            "elementId": 1,
            "id": 331,
            "isHidden": false,
            "isMonitored": true,
            "name": "FS-monitor-warning win-dleith"
         },
         {
            "elementId": 1,
            "id": 1,
            "isHidden": false,
            "isMonitored": true,
            "name": "UPTIME-win-dleith"
         },
         {
            "elementId": 1,
            "id": 4,
            "isHidden": true,
            "isMonitored": true,
            "name": "Configuration Update Gatherer"
         },
         {
            "elementId": 1,
            "id": 2,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-win-dleith"
         }
      ],
      "name": "win-dleith",
      "tags": 
      [
         {
            "id": 1,
            "name": "Windows servers"
         },
         ...
      ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "Windows 7/Server 2008 R2",
      "typeSubtype": "Windows",
      "typeSubtypeName": "Microsoft Windows"
   },
   {
      "description": "",
      "groupId": 1,
      "hostname": "rd-vc2",
      "id": 2,
      "isMonitored": true,
      "monitors": 
      [
         ...
      ],
      "name": "rd-vc2",
      "tags": 
      [
         ...
      ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "VMware vCenter Server 4.1.0 build-491557",
      "typeSubtype": "VcenterServer",
      "typeSubtypeName": "VMware vCenter Server"
   },
   {
      "description": "",
      "groupId": 2,
      "hostname": "rh-01",
      "id": 8,
      "isMonitored": true,
      "monitors": 
      [
         {
            "elementId": 8,
            "id": 306,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-rh-01"
         },
         ...
      ],
      "name": "rh-01",
      "tags": 
      [
         ...
      ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "Linux Red Hat Enterprise Linux 5",
      "typeSubtype": "Linux",
      "typeSubtypeName": "Linux"
   },
   ...
]

Response Field Details

For each returned Element the following fields will be provided:

Field	Type	Description
description	String	Description of this Element.
groupId	Integer	ID for this Elements' parent Element group.
hostname	String	Hostname used to contact this Element.
id	Integer	ID for this Element.
isMonitored	Boolean	Monitoring status for this Element.
monitors	Array	An array listing all monitors that belong to this Element (see Monitors Array below for details).
name	String	The display name of this Element.
tags	Array	An array listing all views/tags that this Element belongs to (see Tags Array below for details).
typeName	String	A basic type definition for the Element. The following types are supported: server network device Application
typeOs	String	Returns basic operating system information for this Element: server: operating system network device: `sysDescr` value Application: no result will be returned Elements of other types are not currently supported by the API.
typeSubtype	String	Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported: server AIX Linux Netware Solaris Windows Hpux EsxServer IbmPowerSystems VcenterServer VcenterHostSystem Unknown network device switch Application Application
typeSubtypeName	String	Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes.

Monitors Array

The monitors array is the same across all end points. For each monitor associated with this Element the following fields will be provided:

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

Tags Array

For each tag or view associated with this Element, the following fields will be provided:

Field	Type	Description
id	Integer	ID of the tag or view
name	String	name of the tag or view

Actions On An Element

View Element Status Summary

Produces basic availability information, similar to the status shown on Global Scan. The 'status' task can only be called against one Element at a time, based on ID.

Endpoint

GET https://youruptime/api/v1/elements/<id>/status

Example Response

GET https://youruptime/api/v1/elements/1/status

{
   "id": 1,
   "isMonitored": true,
   "lastCheckTime": "2012-09-17T14:13:56",
   "lastTransitionTime": "2012-09-13T11:34:38",
   "message": "",
   "monitorStatus": 
   [
      {
         "elementId": 1,
         "id": 7,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:13:56",
         "lastTransitionTime": "2012-09-17T14:05:56",
         "message": "",
         "name": "Default File System Capacity",
         "status": "UNKNOWN"
      },
      {
         "elementId": 1,
         "id": 8,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:13:56",
         "lastTransitionTime": "2012-09-17T14:13:56",
         "message": "",
         "name": "Default Agent Service Check",
         "status": "UNKNOWN"
      },
      ...
   ],
   "name": "win-dleith",
   "powerState": "On",
   "status": "OK",
   "topologyParentStatus": 
   [
      {
         "id": 2,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "rd-vc2",
         "powerState": null,
         "status": "OK"
      },
      {
         "id": 15,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:09:33",
         "lastTransitionTime": "2012-09-13T11:34:32",
         "message": "",
         "name": "vmh-rd6.rd.local",
         "powerState": "On",
         "status": "OK"
      }
   ]
}

Response Field Details

For the returned Element the following fields will be provided:

Field	Type	Description
id	Integer	ID for this service monitor
isMonitored	Boolean	monitoring status for this service monitor
lastCheckTime	String - Date Time	the last time this service monitor was executed successfully
lastTransitionTime	String - Date Time	the last time this service monitor changed status; this field can be used to determine time in the current status
message	String	the output message produced the last time the service monitor was executed
name	String	display name of this Element
powerState	String	the current power state of the Element (only provided for virtual Elements; all other Elements will return null)
status	String	the last known status of this Element
monitorStatus	Array	an array listing the status of all monitors related to this Element. See 'monitor status arrays' below for more detail.
topologyParentStatus	Array	an array listing the status of all topological parent Elements that this Element is a child to. See 'topology status array' for more detail.
masterMonitorsStatus	Array	an array listing the status of all master service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail)
memberMonitorStatus	Array	an array listing the status of all member service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail)

Monitor Status Arrays

The monitorStatus, masterMonitorStatus, and memberMonitorStatus arrays all provide the same response fields for each service monitor listed in the array:

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor
message	String	the output message produced the last time the service monitor was executed
status	String	the last known status of this service monitor
lastCheckTime	String - Date Time	the last time this service monitor was executed successfully
lastTransitionTime	String - Date Time	the last time this service monitor changed status; this field can be used to determine time in the current status

Topology Status Array

The topologyParentStatus array can be used to map topological dependency failures using identified parent child Element relationships.

Field	Type	Description
id	Integer	ID for the parent Element
isMonitored	Boolean	monitoring status for the parent Element
lastCheckTime	String - Date Time	the last time the parent Element was checked successfully
lastTransitionTime	String - Date Time	the last time this parent Element changed status; this field can be used to determine time in the current status
message	String	the output message produced the last time the parent's status changed
name	String	display name of the parent Element
powerState	String	the current power state of the parent Element (only provided for virtual Elements; all other Elements will return null)
status	String	the last known status of the parent Element

Child pages

Working with Elements

Managing Elements

Listing Elements

Endpoint

Example Request

Example Responses

Response Field Details

Actions On An Element

View Element Status Summary

Example Response

Response Field Details