Working with Groups

This following describes all actions that can be executed with Element groups.

Managing Element Groups

Listing Groups

List Element groups visible to the authenticated user account.

Endpoint

To list all Element groups:

GET https://youruptime/api/v1/groups/

To list a specific Element group:

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

Example Request

List all visible Element groups:

GET https://youruptime/api/v1/groups

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

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

Example Responses

GET https://youruptime/api/v1/groups/

[
   {
      "description": "Collects basic performance data",
      "elements": 
      [
         {
            "id": 1,
            "isMonitored": true,
            "name": "win-dleith"
         },
         {
            "id": 2,
            "isMonitored": true,
            "name": "rd-vc2"
          }
      ],
      "groupId": null,
      "id": 1,
      "monitors":
      [
         {
            "elementId": 1,
            "id": 2,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-localhost"
         },
         ...
      ],
      "name": "My Infrastructure",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 2,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Virtual Machines",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 3,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Hosts",
   },
   ...
]

Response Field Details

For each returned Element group, the following fields will be provided:

Field	Type	Description
description	String	description of this Element group
elements	Array	an array listing the Elements that belong to this Element group (see Working with Elements below for details)
groupId	Integer	ID for this Element group's parent group; can return a null value for the top-level group
id	Integer	ID for this Element group
monitors	Array	an array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
name	String	the name of this Element group

Elements Array

For each Element belonging directly to this Element group the following fields will be provided:

Field	Type	Description
id	Integer	ID for the child Element
isMonitored	Boolean	monitoring status for the child Element
name	String	display name for the child Element

Monitors Array

For each service monitor belonging to Elements that belong to this Element group, the following fields will be provided:

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

Actions On An Element Group

View Service Monitor Status Summary

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

Endpoint

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

Example Response

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

{
   "elementStatus": 
   [
      {
         "id": 1,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "win-dleith",
         "powerState": "On",
         "status": "OK"
      },
      ...
   ]
   "id": 1,
   "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"
      },
      ...
   ]
   "name": "My Infrastructure",
   "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"
      },
      ...
   ]
}

Response Field Details

For the returned Element group, the following fields will be provided:

Field	Type	Description
elementStatus	Array	an object listing the status of the parent Element for this monitor (see Element Status Array below for details)
id	Integer	ID for this service monitor
monitorStatus	Array	the output message produced the last time the service monitor was executed
name	String	name of this service monitor
topologyParentStatus	Array	last known status of this service monitor

Element Status Array

If this Element group has child Elements, the following fields will be provided for each:

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

Monitor Status Arrays

If this Element group has children Elements, the following fields will be provided for each service monitor associated with those Elements:

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
isHostCheck	Boolean	returns true if this service monitor is the host check for its parent Element
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor
message	String	output message produced the last time the service monitor was executed
status	String	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, which can be used to determine time at its 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 this service monitor
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, which can be used to determine time at its current status
message	String	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	last known status of the parent Element

Child pages

Working with Groups

Managing Element Groups

Listing Groups

Endpoint

Example Request

Example Responses

Response Field Details

Actions On An Element Group

View Service Monitor Status Summary

Endpoint

Example Response

Response Field Details