Welcome to docs.opsview.com

REST API: Acknowledge

URL: /rest/acknowledge. This requires authentication. Requires ACTIONSOME or ACTIONALL access.

  • GET - Lists all hosts and services that can be acknowledged based on state and user permissions
  • POST - Submit an acknowledgement
  • PUT, DELETE - Not implemented

Access control

ACTIONALL allows setting acknowledgements to any object in Opsview.

ACTIONSOME allows setting of acknowledgements to host or services based on the access object selection.

Note: If a user has ACTIONALL, but only VIEWSOME, the user could set acknowledgements for objects that they cannot view.

Listing services for acknowledgement

You will get a list of services, same as /rest/status/service, but with the following filtering:

  • Only hosts or services in an unhandled state will be shown
  • Only objects that the user will have access to acknowledge will be listed

See the status API for details of the search parameters and the output.

Setting an acknowledgement

Attributes required for setting an acknowledgement:

  • comment - Free text comment regarding acknowledgement. Required.
  • notify - Whether notification should be sent. Defaults to no.
  • sticky - Whether the acknowledgement should be sticky or not. Defaults to no.

These parameters can either be specified in the URL or via input to the REST API. For examplel, in Perl format:

{
    comment => "Covered in ticket number 5675",
    notify  => 1,
    sticky  => 0,
}

If the same parameter is found as input data and in the URL, the input data has priority.

The author of the acknowledgement is taken from the user login information.

Acknowledgements are set asynchronously, so the REST API will return as soon as the acknowledgement submission is entered. There maybe a small delay before the acknowledgement is displayed in the user interface.

On successful submission of acknowledgements, the response will be of the form:

{
    summary => {
        num_hosts    => ...,
        num_services => ...,
    },
    list => {
        hosts    => [ { id => ..., hostname => ... }, ],
        services => [ { id => ..., hostname => ..., servicename => ... }, ],
      }

This reflects the number of hosts and services that this acknowledgement applied to.

In the event of a failure, the response will be:

{
    message => ...,
    detail  => ...,
}

Where message will be one of:

  • Error validating acknowledge parameters.
  • No objects chosen for acknowledgements (this could also appear if the user does not have access to the objects specified).
  • Errors setting acknowledgements - some objects may have been acknowledged.
  • Error when searching for objects.

Object selection

Acknowledgements are set against objects in NagiosĀ® Core - hosts or services.

You can choose hosts or services using the same URL parameters as the status API, with the following rules:

  • No parameters means that no objects are found (status API returns everything if no parameters is passed).
  • Service objects will be returned if you have added a filtering on a parameter which looks for services, otherwise host objects are returned.
  • No errors are raised if objects are not found.

Alternatively you can search for objects using the following parameters, based on the object type you are searching for:

  • hosts:
    • hst.hostid (same as hostid - this parameter takes priority)
    • hst.hostname
    • hst.hostgroupid (this is only for the host group that the host belongs too - this is not based on the host group hierarchy)
    • hst.hostgroupname (only for host's hostgroup, not the hierarchy)
  • services:
    • svc.serviceid (same as serviceid - this parameter takes priority)
    • svc.hs (same as hs)
    • svc.hostgroupid
    • svc.hostgroupname
    • svc.hostid
    • svc.hostname (can use % as wildcard)
    • svc.servicename (can use % as wildcard)
    • svc.keywordid
    • svc.keywordname
    • svc.servicegroupname
    • svc.servicecheckid

Note: Hosts and services will only be found if you have the appropriate access to the object.

The basic rule is that if you are searching for multiple fields of the same type of object, then the search fields are AND'd together, but multiple values of the same field are OR'd together.

Duplicated host or services are ignored.

If you request a specific object (using hst.hostname, hst.hostid, svc.hs, svc.serviceid) and that object does not exist, an error is raised:

{
    message => "Error when searching for objects",
    detail =>
      "Cannot find host with name nosuchhost; Cannot find host with id 3",
}

In no objects are found, an error is returned:

{ message => "No objects chosen for acknowledgements" }

For example, URL parameters of:

  ...?svc.hs=hostA::service1&svc.serviceid=45&svc.hostname=hostB&svc.hostname=hostC&svc.servicename=HTTP&svc.servicename=Disk:%

This would select the service hostA::service1, the service with id=45, and all services called HTTP or Disk:% on hostB or hostC.

Navigation
Print/export
Toolbox