opCharts Status API

1 Status API
2 Public API for opCharts Status "http[s]://server/omk/opCharts/v2/status"
3 API Routes
4 Request Modifiers (query parameters)
5 GET of opcharts/v2/status for List
- 5.1 Successful Response
- 5.2 Unsuccessful Response
- 5.3 Example
6 GET of opcharts/v2/inventory/inventory_id/status for List
- 6.1 Successful Response
- 6.2 Unsuccessful Response
- 6.3 Example
7 GET of opcharts/v2/status/id
- 7.1 Successful Response
- 7.2 Unsuccessful Response
- 7.3 Example
- 7.4 Properties
8 Add threshold definition reference to status records

Status API

This opCharts API provides access to Status collection data in a JSON format.

The Status API is available in opCharts from version 4.7.0

Authentication is required to access all methods below. See opCharts REST API Reference.

Public API for opCharts Status "http[s]://server/omk/opCharts/v2/status"

We can view opCharts Status below using these endpoints - http[s]://server/omk/opCharts/v2/status

API Routes

Request Method	Operation	URL Example	id required	Notes

Request Method	Operation	URL Example	id required	Notes
GET	read list	/`server/omk/opCharts/v2/status`	n	Returns a list of all the status records (status id and node_uuid) Paginated
GET	read one	/`server/omk/opCharts/v2/status/id`	y	Returns the details of the status record with the given id.
GET	read list	/`server/omk/opCharts/v2/nodes/node_uuid/status`	y	Returns a list of all the status records (status id and node_uuid), matching given node_uuid Paginated
GET	read list	/`server/omk/opCharts/v2/inventory/inventory_id/status`	y	Returns a list of the (status id and node_uuid) for all the Status objects matching inventory_id Paginated
GET	read list	/`server/omk/opCharts/v2/nodes` `/node_uuid/inventory/inventory_id/status`	y	Returns a list of all the status records (status id and node_uuid), matching given node_uuid and inventory_id. Paginated

Request Modifiers (query parameters)

The properties request modifier tells opCharts which properties you would like listed, query limits the requested resources to only those that match all criteria given. This collection can paginated, it is also limited to 25 results by default (this could be subject to change in future opCharts versions) use the limit query parameter to request more nodes

Not all requests will use all request modifiers.

Query Parameter	Possible Values

Query Parameter	Possible Values
`properties`	Array of property names. If provided only the properties specified will be returned (instead of the whole document). eg: `properties=["event","lastupdate"]` By default the nodes UUID is returned by default if no properties are given
`page`	(int) Which page of the requested document to return, defaults to 1
`limit`	(int) How many results to return, defaults to 25
`filter`	Array of key=value pairs, but coded in an array. Applied to the list of results in the order they are given. If an application key is provided that will be applied first. eg: filter={"level":"Normal"}
`sort`	-1 \| 1 : sort the response with id ascending or descending.

Examples of how to use the request modifiers can be found in the response blocks below. In general, the queries will look something like this:

GET of opcharts/v2/status for List

GET /omk/opCharts/v2/status

You will get a list of all the Status records in your database.

Successful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
200 OK	Possibly empty JSON array of strings	Each array element is a JSON string object with the subconcept name

Unsuccessful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
401 Unauthorized	JSON object with an `error` property	You are not authenticated.
403 Forbidden	JSON object with an `error` property	You are not authorized.

Example

GET HTTP://server/omk/opCharts/v2/status.json

Output:- List of first 25 status objects, sorted by id
[
	{
		"id": "648a0e4ca44a3ab377278383",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
	{
		"id": "648a0e4ca44a3ab377278389",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
	{
		"id": "648a0e4ca44a3ab37727838c",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
	{
		"id": "648a0e4ca44a3ab377278542",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
    . . .
]

GET of opcharts/v2/inventory/inventory_id/status for List

GET /omk/opCharts/v2/inventory/inventory_id/status

You will get a list of the first 25 status objects for the given inventory_id in your database.

You can use Request Modifiers (see above) for filtering, pagination, and selecting properties.

Successful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
200 OK	Possibly empty JSON array of strings	Each array element is a JSON string object with the subconcept name

Unsuccessful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
400 Bad Request	JSON object with an `error` property
401 Unauthorized	JSON object with an `error` property	You are not authenticated.
403 Forbidden	JSON object with an `error` property	You are not authorized.
404 Not Found	JSON object with an `error` property	You are authenticated but not authorised to view this object.
404 Not Found	JSON object with an `error` property	The `error` property contains an explanation of what went wrong with your request, e.g. if you request a non-existent object.

Example

GET HTTP://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json

Output :- List of first 25 status objects ("id" and "node_uuid") sorted by id in ascending order.  
[
	{
		"id": "648a0e4ca44a3ab377278383",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
	{
		"id": "648a0e4ca44a3ab377278389",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	},
	{
		"id": "648a0e4ca44a3ab37727838c",
		"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
	}
]

Similar requests and descriptions with subconcepts

Request	Response

Request	Response
GET http://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json	First 25 elements sorted by id ("id" and "node_uuid")
GET http://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json?limit=50&page=2	Next 50 elements sorted by id ("id" and "node_uuid")
GET http://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json?limit=50&properties=["node_name"]	First 50 elements sorted by id ("id" , "node_uuid", "node_name")
GET http://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json?imit=50&page=2&properties=["event"]	Next 50 elements sorted by id ("id" , "node_uuid", "event")
GET http://server/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json?limit=50&properties=["node_name"]&filter={"level":"Normal"}	First 50 elements sorted by id, filtered by level = Normal ("id" , "node_uuid", "node_name")
GET http://server/en/omk/opCharts/v2/inventory/648a0baea44a3ab37721db6d/status.json?properties=["event","lastupdate"]&filter={"level":"Normal"}	First 25 elements sorted by id displaying 2 properties [ { "event": "Proactive Response Time", "id": "648a0e4ca44a3ab377278383", "lastupdate": 1687213025, "node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa" }, { "event": "Proactive Reachability", "id": "648a0e4ca44a3ab377278389", "lastupdate": 1687213025, "node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa" } ]

GET of opcharts/v2/status/id

GET /omk/opCharts/v2/status/id

You will get a single objects for the given id in your database.

You can use Request Modifiers (see above) for filtering, pagination, and selecting properties.

Successful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
200 OK	Possibly empty JSON array of strings	Each array element is a JSON string object with the subconcept name

Unsuccessful Response

HTTP Status	Body	Description

HTTP Status	Body	Description
401 Unauthorized	JSON object with an `error` property	You are not authenticated.
403 Forbidden	JSON object with an `error` property	You are not authorized.

Example

http://server/omk/opCharts/v2/status/648a0e4ca44a3ab377278383.json

{
"class": null,
"cluster_id": "9ed25c17-9ec2-4034-94e6-f6c932ad273b",
"element": null,
"event": "Proactive Response Time",
"id": "648a0e4ca44a3ab377278383",
"index": null,
"inventory_id": "648a0baea44a3ab37721db6d",
"lastupdate": 1687213025,
"level": "Normal",
"method": ,
"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa",
"property": "response",
"status": "ok",
"type": "health",
"value": 8.59
}

Properties

These properties are also displayed on the opCharts → Views → Status page, see the headings below:

Property	Description	Example	Status page
`id`	A globally unique ID	`"63576103ad794974594a1f11"`
`class`	optional
`cluster_id`	The `id` of the NMIS poller server for the associated node	`"6678b17aca40037e1139cace"`
`element`	optional		Element
`event`	The Event from the Event Configuration. page, Administration → Configuration → Event Configuration	`"Proactive Response Time"`	Event
`index`	optional
`inventory_id`	The `id` of the associated inventory record. See opCharts Inventory API.	`"648a0baea44a3ab37721db6d"`
`lastupdate`	The unix timestamp that this status record was last updated.	`1687213025`	Last Update
`level`	One of Normal Warning Minor Major Critical Fatal	`"Normal"`	Level
`method`	optional	`"Alert"` or `"Threshold"`	Method
`name`	optional		Name
`node_uuid`	The `uuid` of the associated node	`"8da86248-40f3-4c92-90b6-736bb66814aa"`	Node
`property`		`response`
`status`		`"ok"` or `"error"`	Status
`type`		`"health"`
`value`		`8.59`

Similar requests and descriptions with inventory id

Request	Response

Request

Response

GET HTTP://server/omk/opCharts/v2/status/648a0e4ca44a3ab377278383.json

Raw inventory element with given object id

GET HTTP://server/omk/opCharts/v2/status/648a0e4ca44a3ab377278383.json?properties=["event"]

Raw inventory element with given object id, event and node_uuid

{"event": "Proactive Response Time",
"id": "648a0e4ca44a3ab377278383",
"node_uuid": "8da86248-40f3-4c92-90b6-736bb66814aa"
}

Add threshold definition reference to status records

Added the following new fields to NMIS status records to allow identification of the threshold definition used to generate each status document (added in OMK-12375).

Property	Description	Example

Property	Description	Example
threshold_key	Name of the threshold or alert as defined in the model. For Threshold method this is the threshold name; for Alert method it is the alert name or data source name.	"util_out"
threshold_metric	The model data source / metric being evaluated. For standard thresholds this is the model's item field. For custom alerts it is the first CVAR=<name> variable in the alert's value expression — the SNMP object name the alert is computed from.	"outputUtil"
threshold_select	The key of the select block in the threshold model definition whose control expression matched. Numeric keys are evaluated in ascending order and the first match is used. "default" means no control matched and the fallback block applied.	20
threshold_source	The .nmis model file that defined this threshold or alert. Populated from a _source_file tag injected into model items during model loading, enabling traceability back to the originating file.	"Common-threshold"
threshold_unit	Unit of the measured value, taken from the unit field of the threshold or alert definition in the model.	"%"
model_subconcept	The model section (type/subconcept) the threshold belongs to — the RRD section name or systemHealth type that contains the metric definition.	"interface"